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:

Zendesk recommends using cursor pagination instead of offset pagination where possible. Cursor pagination provides greatly improved performance when retrieving extremely large record sets.

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 paginationCursor pagination
Specify which page of items to returnSpecify the page request parameterSpecify the page[after] or page[before] request parameter
Specify how many items to return per pageSpecify the per_page request parameterSpecify the page[size] request parameter
Sort the items in a certain orderSpecify the sort_by and/or sort_order request parametersSpecify the sort request parameter.
Determine the URL of the next or previous page of itemsUse the next_page or previous_page response propertyUse the links[prev] or links[after] response property
Determine when there are no more items in the result setWhen the next_page response property is nullWhen the meta[has_more] response property is false
Determine the total number of itemsUse the count response propertySee 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.