Pagination

How Pagination Works

Most list queries in the Pluvo API use Relay-style cursor pagination. This means results are returned in pages, and you use cursors to navigate between them.

Response structure

Paginated queries return a Connection type with this structure:

{
  edges {
    node { ... }    // The actual object
    cursor          // Opaque cursor string
  }
  pageInfo {
    hasNextPage     // Are there more results?
    endCursor       // Cursor for the next page
  }
  count             // Total number of results
}

Fetching the first page

Use the first parameter to specify how many items you want per page (maximum 50):

query {
  paginatedUsers(first: 50) {
    edges {
      node {
        id
        name
        email
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    count
  }
}

Fetching the next page

Pass the endCursor from the previous response as the after parameter:

query {
  paginatedUsers(first: 50, after: "cursor-from-previous-page") {
    edges {
      node { id name email }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Looping through all results

To fetch all results, repeat the query until hasNextPage is false:

1. Query with first: 50 (no after parameter)
2. Process the results
3. If hasNextPage is true: query again with after: endCursor, go to step 2
4. If hasNextPage is false: done

Complete example: fetch all users

query GetAllUsers($cursor: String) {
  paginatedUsers(first: 50, after: $cursor, archived: false) {
    edges {
      node {
        id
        name
        email
        ref
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    count
  }
}

First call: variables: {}

Subsequent calls: variables: { "cursor": "<endCursor from previous response>" }

Queries that support pagination

Best practices

• The maximum page size is 50. Requesting more than 50 will return an error or be capped to 50.
• Use first: 50 for maximum efficiency per request.
• Always check hasNextPage — don't assume there's another page based on result count.
• Use count from the first response to estimate total pages or show progress.
• For full exports, use first: 50 and loop through all pages.
• For real-time sync, use webhooks instead of polling paginated queries.