Comparing cursor pagination and offset pagination
The Zendesk Support, Talk, and Help Center APIs have several endpoints that return lists of items, such as tickets, users, or articles.
For performance reasons, the APIs do not return large record sets all at once. Instead, they break up the results into smaller subsets and return them in pages. The number of items per page varies by endpoint. For example, the tickets and users endpoints return 100 items per page while the articles endpoint returns 30 items per page.
Zendesk has two methods of paginating through resources:
- Offset pagination (previously referred to as just pagination). This method is supported by all resources. See Paginating through lists using offset pagination for detailed instructions.
- Cursor pagination. This method is supported by most resources, such as tickets and users, and will be progressively introduced to all resources. See Paginating through lists using cursor pagination for detailed instructions.
Zendesk recommends using cursor pagination instead of offset pagination where possible. Cursor pagination provides greatly improved performance when retrieving extremely large record sets. A limit applies when using offset pagination. See Offset pagination limit.
The request parameters and the format of the returned JSON object differ between cursor pagination and offset pagination. The following table summarizes the key differences:
| How do I... | Offset pagination | Cursor pagination |
| Specify which page of items to return | Specify the page request parameter | Specify the page[after] or page[before] request parameter |
| Specify how many items to return per page | Specify the per_page request parameter | Specify the page[size] request parameter |
| Sort the items in a certain order | Specify the sort_by and/or sort_order request parameters | Specify the sort request parameter. |
| Determine the URL of the next or previous page of items | Use the next_page or previous_page response property | Use the links[prev] or links[after] response property |
| Determine when there are no more items in the result set | When the next_page response property is null | When the meta[has_more] response property is false |
| Determine the total number of items | Use the count response property | See the API documentation for the specific resource |
Each resource has different limits on how many items can be returned per page and how results can be sorted or filtered. See the API documentation for the specific resource.
Incremental export endpoints can also be used to get large data sets of certain resources, such as tickets and users. For details, see Incremental Exports.
Another option for getting large data sets is to use the reporting feature in Zendesk Support to export data to a CSV or XML file. For details, see Exporting data to a CSV or XML file.
See also Pagination in the Introduction of the Zendesk REST API documentation.