Pagination with the API

There are two methods of pagination: cursor-based and page-based. Cursor-based pagination is not available for every sort order on every collection, but it should be preferred whenever it is available because it offers a more reliable ordering of results and more consistent API performance. There is also a Link header provided which will make this decision for you.

In either case the number of records you receive is controlled by the per_page parameter. The default per_page is 20 and the maximum is 100. There will be a pagination object in the response with metadata about the current page:

  "pagination": {
    "page": 1,
    "per_page": 100,
    "total_pages": 3,
    "total_records": 272
  }

Cursor-based pagination

When you get the first page of results, if cursor-based pagination is supported, there will be a cursor value in the pagination part of the response. Pass this cursor value as a parameter to the same endpoint to retrieve the next page of results along with a new cursor value.

Example:

GET /api/v2/admin/suggestions?sort=-supporters_count
{
    "suggestions": [ … ],
    "pagination": {
        "total_records": 200,
        "total_pages": 10,
        "page_size": 20,
        "page": 1,
        "cursor": "eyJzb3J0IjoiIiwidmFsIjoyNjMsImxhc3RfaWQiOjIzMTUyMjJ9"
    }
}

GET /api/v2/suggestions?cursor=eyJzb3J0IjoiIiwidmFsIjoyNjMsImxhc3RfaWQiOjIzMTUyMjJ9&sort=-supporters_count
{
    "suggestions": [ … ],
    "pagination": {
        "total_records": 200,
        "total_pages": 10,
        "page_size": 20,
        "page": 1,
        "cursor": "eyJzb3J0IjoiIiwidmFsIjoxNzgsImxhc3RfaWQiOjIwODc3OX0="
    }
}

When using cursor-based pagination the page value in the response will always be 1. You will know that you are on the last page of results when there is no longer a cursor value in the response.

With cursor-based pagination you must always start at the beginning of a list and work your way forward. It is not possible to move backward or to jump to certain offset the way you can with page-based pagination. A cursor token can only be used to request records in the same sort order as the request that provided it. If you want the records in a different order, you must start at the beginning without a cursor parameter.

The cursor represents a fixed point in the ordered set of results. If you change the per_page parameter when using a cursor you will get a different number of results but they will start with the same record.

Cursor-based pagination is ideal for scenarios where you want to pull a long list of records from the API. Its performance should be basically constant from the first page of results to the last, whereas page-based pagination will degrade in performance the deeper you get into the list.

Another benefit of cursors is that your position in the list will not be shifted if objects are created or deleted while you are paging. With page-based pagination those events could result in a record being skipped, or a record being returned twice.

Page-based pagination

With page-based pagination, the records you get are determined by multiplying the page number by the per_page parameter. To get the next page of results, you simply increment the page parameter.

Example:

GET /api/v2/admin/suggestions?sort=-cf_my_field
{
    "suggestions": [ … ],
    "pagination": {
        "total_records": 200,
        "total_pages": 10,
        "page_size": 20,
        "page": 1
    }
}

GET /api/v2/suggestions?sort=-cf_my_field&page=2
{
    "suggestions": [ … ],
    "pagination": {
        "total_records": 200,
        "total_pages": 10,
        "page_size": 20,
        "page": 2
    }
}

If you change the per_page parameter when requesting a page other that 1, you will get completely different results since the offset is computed by (page - 1) * per_page.

Page-based pagination is different from cursor-based pagination. If records are added or removed while retrieving paginated results, items may appear to shift across pages. Paginated results also do not perform as well as cursor-based results. Use cursor-based pagination wherever it is available.

Link header

A link header is provided along with every API response when another page of results is available. If you are on the last page of results, there will not be a link header.

Cursor example:

Link: </api/v2/admin/suggestions?cursor=eyJzb3J0IjoiIiwidmFsIjoxNzgsImxhc3RfaWQiOjIwODc3OX0%3D&sort=-supporters_count>; rel=next

Page example:

Link: </api/v2/admin/suggestions?page=2&sort=-cf_my_field>; rel=next

The link header will automatically switch between page-based and cursor-based pagination depending on whether the latter is available for the requested sort order.