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.