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.
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": [ ... ],
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
previous_page URLs in the response body for easier navigation:
"users": [ ... ],
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=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.