Pagination with Prismatic's API

By default, most queries return a maximum of 100 results. If you have more than 100 records of a particular type (say, more than 100 instances), you can pull down 100, process those results, and then ask for the next 100 results, etc., until you process all records.

If you would like to fetch fewer than 100 records at a time, you can specify a first property in your query.

To request page info, add pageInfo alongside the nodes of any query. pageInfo has several properties - the two you'll likely be interested in are hasNextPage, which tells you if more results are available, and endCursor, which is an indicator of where your query "left off", so your next query can pick up from there.

Fetch the second page of 10 instances using a cursor

query getPageOfInstances($cursor: String) {
  instances(
    after: $cursor
    isSystem: false
    sortBy: [{field: CREATED_AT, direction: ASC}]
    first: 10
  ) {
    nodes {
      id
      name
      customer {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Query Variables

{
  "cursor": "YXJyYXljb25uZWN0aW9uOjk5"
}

Try It Out ❯

After fetching your results, you can check if pageInfo.hasNextPage is true. If it is, grab the pageInfo.endCursor (which might read something like YXJyYXljb25uZWN0aW9uOjEwMA==) and run the same query, changing your query variables to read

{ "cursor": "YXJyYXljb25uZWN0aW9uOjEwMA==" }

That cursor query variable will be used by the query above as the after property. That will cause the API to fetch up to 100 more results, but instead of starting at the beginning the API will start where your previous query left off.

sort order is important when paginating

When fetching multiple pages of results, sort order is important. Without a sort order, two consecutive pages may contain duplicate records, or you may miss records.

Most queries support a CREATED_AT sort field, which will sort results by the time they were created. In the query above, instances were sorted by creation date in ascending order with sortBy: [{field: CREATED_AT, direction: ASC}]

Some record types like logs do not have a CREATED_AT field, but have a TIMESTAMP field that you can sort by instead. components are versioned, and versions of components can be sorted by VERSION_CREATED_AT.