Pagination

Most list endpoints support two methods of paginating through results—cursor pagination and offset pagination. See the API documentation for an endpoint to determine which pagination methods it supports. If no pagination method is specified, the endpoint only supports offset pagination.

Zendesk recommends using cursor pagination instead of offset pagination where possible. Cursor pagination provides greatly improved performance when retrieving extremely large record sets. See Comparing Cursor Pagination and Offset Pagination for further details on the differences between the pagination methods.

Using cursor pagination

To use cursor pagination, include the page[size] parameter in the request parameters. This parameter is also used to specify the number of items to return per page. Most endpoints limit this to a maximum of 100. If you omit the page[size] parameter, offset pagination is used. See the API documentation for the specific resource.

Example

For example, a request to the tickets endpoint with the URL https://example.zendesk.com/api/v2/tickets.json?page[size]=100 would return a response with the following format:

"tickets": [ ... ],
"meta": {
  "has_more": true,
  "after_cursor": "xxx",
  "before_cursor": "yyy"
},
"links": {
  "next": "https://example.zendesk.com/api/v2/tickets.json?page[size]=100&page[after]=xxx",
  "prev": "https://example.zendesk.com/api/v2/tickets.json?page[size]=100&page[before]=yyy"
}

The values xxx and yyy are placeholder values that represent cursors.

Use the URL in the links[next] property to retrieve the next page of results. Using the above example, make a request to https://example.zendesk.com/api/v2/tickets.json?page[size]=100&page[after]=xxx to retrieve the next page of results.

In the Help Center API, the next link is also available in the "Link" HTTP response header. Example:

Link: <https://example.com/api/v2/help_center/en-us/articles?page%5Bafter%5D=xxx&page%5Bsize%5D=100>; rel="next"

Repeat the above steps until the meta[has_more] property is false. This indicates there are no further records and you should stop paginating.

In the Help Center API, you can also paginate backwards. Follow the links[last] link to jump to the final page. Then, as long as has_more is true, follow the prev link to step backwards one page at a time until has_more is false. Like the next link, the prev link is also available in the "Link" HTTP response header.

For more detailed instructions and code examples, see Paginating Through Lists Using Cursor Pagination.

Using offset pagination

If you do not opt-in to cursor pagination as described above, offset pagination will be used by default. A limit may apply when using offset pagination with high-volume requests. See Offset Pagination limit.

By default, most list endpoints return a maximum of 100 records per page. You can change the number of records on a per-request basis by passing a per_page parameter in the request URL parameters. Example: per_page=50. However, you can't exceed 100 records per page on most endpoints.

When the response exceeds the per-page maximum, you can paginate through the records by incrementing the page parameter. Example: page=3. List results include next_page and previous_page URLs in the response body for easier navigation:

{
  "users": [ ... ],
  "count": 1234,
  "next_page": "https://account.zendesk.com/api/v2/users.json?page=2",
  "previous_page": null
}

Stop paging when the next_page attribute is null. For more information, see Paginating Through Lists Using Offset Pagination

Inaccuracies may be introduced in pages because of the limitations of API pagination. For more information and options, see Limitations of API pagination.

Some lists can be ordered by transmitting a sort_order=desc or sort_order=asc parameter to the end point. Whether a specific list can be ordered is specified in the documentation for that specific resource.

Some endpoints limit the page number, or rate limit requests above a certain page number. See the documentation for the specific endpoint.

Offset pagination limit

Requests that use offset pagination are limited to 10 next_page requests per minute after the first 1,000 pages (and 100,000 resources).

If a request exceeds this limit, you'll get a 429 status code, and the remaining request will need to be retried later. The response header will include a Retry-After value to indicate the wait time before retrying the request.

Other pagination methods

Certain endpoints use different pagination methods:

• Incremental export endpoints use a variant of cursor pagination with some differences. See Cursor-based incremental exports in Using the Incremental Exports API article for more information.
• The List All Ticket Audits endpoint uses a variant of cursor pagination with some differences. See Pagination in the List All Ticket Audits documentation.