The Support API has several endpoints that return lists of items, such as tickets and users. This article explains how to paginate through the lists.

For bandwidth reasons, the API doesn't return large record sets all at once. It breaks up the results into smaller subsets and returns them in pages. The number of items per page varies by endpoint. The tickets and users endpoints return 100 items per page while the articles endpoint returns 30 items per page.

You must paginate through the results to get all the data. This article explains how basic pagination works.

The pagination methods discussed in this article are supported by following Zendesk APIs:

  • Support API
  • Help Center API
  • Talk API

The pagination details of other APIs might be different but the logic is the same.

Topics covered:

See also Pagination in the Introduction of the Zendesk REST API documentation.

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk does not support or guarantee the code. Zendesk also can't provide support for third-party technologies such as Python and Perl. Please post any issue in the comments section or search for a solution online.

Choosing a pagination method

The Support API has two pagination methods: offset and cursor-based.

  • In offset pagination, Zendesk keeps a record count and "turns the page" after reaching a specific number of records (the offset number).
  • In cursor-based pagination, Zendesk uses a pointer in the recordset to keep track of the next record. The pointer moves in the recordset like the cursor in a text editor indicating where the next words you type will appear. Zendesk paginates based on the position of the pointer in the recordset.

Zendesk recommends using cursor-based pagination when it's available. It's currently available only for certain list endpoints in the Support API, including List Tickets and List Users. If the API documentation for a specific list endpoint doesn't specify that cursor-based pagination is available, then the resource only supports offset pagination.

See also Understanding the limitations of offset pagination.

Adding pagination with the offset method

The offset pagination method is supported by all list endpoints in the Support, Help Center, and Talk APIs.

By default, the JSON objects returned by list endpoints contain a next_page property with the URL of the next page of results, if any. Example:

"users": [ ... ],"next_page": "https://example.zendesk.com/api/v2/users.json?page=2",...

If there's no next page, the value is null.

"users": [ ... ],"next_page": null,...

Your code should check the next_page property when it calls any list endpoint. If null, it can move on. If not null, it should make another request using the specified URL.

The following pseudo code is a common pattern for paginating through items:

url = 'https://example.zendesk.com/api/v2/users.json'while url is not nothing:    response = request(url)    // do something with the response    // but don't dally    url = response('next_page')

Don't wait too long between next page requests because the real-time nature of the data could introduce inaccuracies in the pagination results. See Understanding the limitations of offset pagination.

Python example

Here's a Python example that uses the third-party requests library:

url = 'https://example.zendesk.com/api/v2/help_center/sections/200646/articles.json'while url:    response = requests.get(url)    data = response.json()    for article in data['articles']:        print(article['title'])    url = data['next_page']

After getting and processing the first page of results, the script checks the value of the next_page property. If the value is null, which Python considers false, the loop stops.

Adding pagination with the cursor-based method

The cursor-based pagination method is supported by certain list endpoints in the Support API. Examples include List Tickets and List Users. If the API documentation for a specific list endpoint doesn't specify that cursor-based pagination is available, then the resource only supports offset pagination.

When using this method, requests return a meta object and links object along with the list of requested records. The links object has a next property with the URL of the next page of results, if any. Example:

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

Note: The url values in the example will be url-encoded in actual use.

Keep paginating until the has_more property in the meta object is false then stop.

By default, the pagination method for all list endpoint is the offset method. To use cursor-based pagination, you must include a page[size] query parameter. Example:

https://example.zendesk.com/api/v2/users.json?page[size]=100

The following pseudo code is a common pattern for paginating through items with cursor-based pagination:

url = 'https://example.zendesk.com/api/v2/users.json?page[size]=100'while url is not nothing:    response = request(url)    // do something with the response    if response('meta.has_more') is true:        url = response('links.next')    else:        url = nothing

Python example

Here's a Python example that uses the third-party requests library:

auth = '[email protected]', 'mypassword'url = 'https://example.zendesk.com/api/v2/tickets.json?page[size]=100'
while url:    response = requests.get(url, auth=auth)    data = response.json()    for ticket in data['tickets']:        print(ticket['id'])
    if data['meta']['has_more']:        url = data['links']['next']    else:        url = None