Cursor-based Pagination

If it is included in your contract, you may use a separate cursor based pagination method to page through the entire result set of a specific query.

Enabling Cursor Pagination

To determine if a query supports cursor based pagination, look for the paginationType parameter, such as on the podcasts query. You can set this to CURSOR to enable cursor pagination on that query.

Using Cursors

When using cursor based pagination, instead of specifying which page of results you would like to retrieve, you will use the cursor returned from the previous query to specify where the next query should start. For this reason, you can only ever start from the beginning of a set of results and go through them a page at a time.

The cursor to use for the next page of results is returned in the cursorInfo object, along with the total number of results found by the query.

When you pass this cursor to the cursor parameter of the query, you will receive the next page of results and a new cursor to continue paginating.

caution

Your filters and sort parameters must stay the same for each query when you are paging through a set of results using cursors. If they are changed you may receive error messages or inaccurate results.

Cursor Expiration

To allow for deep cursor-based pagination, we employ a snapshot system to ensure a particular set of results stays consistent while the queries are underway. To avoid using large amounts of resources, these snapshots have a time limit of 1 minute. To ensure accurate results, you should leave no longer than 1 minute between subsequent cursors for a particular query.

If a cursor expires, a new one will be automatically generated so you can continue where you left off, but it is possible your results may not be exhaustive. If this has occurred, the cursorRefreshed field will be true.

Example Query

Here is an example of a podcast query for paging through results using cursor pagination.

{
  podcasts(first: 2, sort: {sortBy: FOLLOWER_COUNT, direction: DESCENDING}) {
    data {
      id
    }
    cursorInfo {
      total
      nextCursor
    }
  }
}

And here is the response, with an example cursor (the real cursor will be a significantly longer string)

{
  "data": {
    "podcasts": {
      "data": [
        {
          "id": "10829"
        },
        {
          "id": "39961"
        }
      ]
    }
  },
  "cursorInfo":{
    "total": 1842893,
    "nextCursor":"eyJzb3J0IjpbMTI4ODQ5MDE5MTJdLCJwaXRfaWQiOiJURVNUX1BJVF9JRCJ9"
  }
}

To get the next page of results, you would then add that cursor as a parameter to your next query, like so:

{
  podcasts(cursor: "eyJzb3J0IjpbMTI4ODQ5MDE5MTJdLCJwaXRfaWQiOiJURVNUX1BJVF9JRCJ9", first: 2, sort: {sortBy: FOLLOWER_COUNT, direction: DESCENDING}) {
    data {
      id
    }
    cursorInfo {
      total
      nextCursor
    }
  }
}