| Announced on | Rolled out on |
| May 22, 2023 |
|
Zendesk currently offers both offset-based pagination (OBP) and cursor-based pagination (CBP) for most API endpoints. CBP offers many advantages over OBP and will be the primary method of pagination offered at Zendesk in the near future. In an effort to provide a better, faster experience for our customers we are taking steps to encourage a transition to CBP – starting with the introduction of tighter limits on high-offset OBP requests.
This announcement answers the following questions:
What is changing?
Beginning on August 22, 2023, OBP requests over the first 10,000 records (100 pages) will result in an error message: “400 Bad Request.” In order to request data sets larger than 10,000 records, customers will need to transition to CBP.
OBP requests for fewer than 10,000 records will not be affected, nor will requests made using the CBP model.
Why is Zendesk making this change?
We are making this change in line with our previous announcement recommending the adoption of CBP and encouraging customers to make the switch as soon as possible.
Cursor-based pagination is faster and more efficient for our customers. It also puts less strain on Zendesk infrastructure and increases stability and reliability. As a first step, we are limiting offset-based pagination capabilities at a relatively high level, so that the transition can take place with minimal disruption to current API usage.
What do I need to do?
Zendesk strongly encourages customers to make the transition to cursor-based pagination before August 22, 2023. If you do not know which integrations or applications may be going over the limit, we suggest partnering with your team responsible for managing Zendesk integrations and apps to investigate and determine what this change means for you.
Zendesk will be continue to offer Offset Pagination but will significantly limit the page depth in the near future to encourage adoption of high performant Cursor Pagination and improve response times for your requests.
Should you have questions or need additional support, please contact us and we’ll be happy to help. You can reach out to us via the web widget.
Updates available for Client Libraries/SDKs
Zendesk has updated its Official Ruby client, and partnered with developers of the community SDKs to provide CBP support. If you are using one of these libraries, please review, test and update to the latest version.
| Library | Helpful Instructions |
| Ruby |
>=3.0.4 supports Cursor Pagination Refer to General Usage in the Wiki. |
| Python |
>=v2.0.34 supports Cursor Pagination pip install zenpy --upgrade |
| NodeJS |
>=v3.0.2 supports Cursor Pagination. Refer to the release tag here. npm update node-zendesk |
Endpoints with CBP Capability
| Product | Endpoint |
| Ticketing | /api/v2/views |
| Ticketing | /api/v2/users |
| Ticketing | /api/v2/triggers/active |
| Ticketing | /api/v2/triggers |
| Ticketing | /api/v2/tickets_audits |
| Ticketing | /api/v2/tickets (including /incremental/*) |
| Ticketing | /api/v2/ticket_metrics |
| Ticketing | /api/v2/ticket/:ticket_id/audits |
| Ticketing | /api/v2/tags |
| Ticketing | /api/v2/suspended_tickets |
| Ticketing | /api/v2/skips |
| Ticketing | /api/v2/satisfaction_ratings |
| Ticketing | /api/v2/requests/:request_id/comments |
| Ticketing | /api/v2/recipient_addresses |
| Ticketing | /api/v2/organizations/:organization_id/subscriptions |
| Ticketing | /api/v2/organizations/:organization_id/tickets |
| Ticketing | /api/v2/organizations/:organization_id/users |
| Ticketing | /api/v2/organizations |
| Ticketing | /api/v2/oauth/tokens |
| Ticketing | /api/v2/oauth/global_clients |
| Ticketing | /api/v2/oauth/clients |
| Ticketing | /api/v2/macros |
| Ticketing | /api/v2/groups/assignable |
| Ticketing | /api/v2/groups/:group_id/memberships |
| Ticketing | /api/v2/groups |
| Ticketing | /api/v2/group_memberships |
| Ticketing | /api/v2/deleted_tickets |
| Ticketing | /api/v2/automations |
| Ticketing | /api/v2/activities |
| Brands | /api/v2/brands |
| Help Center | /api/v2/help_center/{locale}/articles |
| Help Center | /api/v2/help_center/{locale}/articles/:article_id/comments |
| Help Center | /api/v2/help_center/{locale}/articles/:article_id/labels |
| Help Center | /api/v2/help_center/{locale}/articles/:article_id/subscriptions |
| Help Center | /api/v2/help_center/{locale}/articles/:article_id/votes |
| Help Center | /api/v2/help_center/{locale}/categories/:category_id/articles |
| Help Center | /api/v2/help_center/{locale}/categories/:category_id/sections |
| Help Center | /api/v2/help_center/{locale}/sections |
| Help Center | /api/v2/help_center/{locale}/sections/:section_id/subscriptions |
| Help Center | /api/v2/help_center/{locale}/sections/:section_id/articles |
| Help Center | /api/v2/help_center/articles/:article_id/translations |
| Help Center | /api/v2/help_center/articles/labels |
| Help Center | /api/v2/help_center/categories/:category_id/translations |
| Help Center | /api/v2/help_center/incremental/articles?start_time={start_time} |
| Help Center | /api/v2/help_center/sections/:section_id/translations |
| Help Center | /api/v2/help_center/user_segments |
| Help Center | /api/v2/help_center/user_segments/:user_segment_id/topics |
| Help Center | /api/v2/help_center/user_segments/applicable |
| Help Center | /api/v2/help_center/users/:user_id/comments |
| Help Center | /api/v2/help_center/users/:user_id/subscriptions |
| Help Center | /api/v2/help_center/users/:user_id/user_segments |
| Help Center | /api/v2/help_center/users/:user_id/votes |
| Help Center | /api/v2/help_center/users/:user_id/articles |
| Help Center | /api/v2/community/topics |
| Help Center | /api/v2/community/posts/:post_id/comments |
| Help Center | /api/v2/community/posts/:post_id/comments/:comment_id/votes |
| Help Center | /api/v2/community/posts/:post_id/subscriptions |
| Help Center | /api/v2/community/posts/:post_id/votes |
| Help Center | /api/v2/community/topics/:topic_id/subscriptions |
| Help Center | /api/v2/community/users/:user_id/posts |
| Help Center | /api/v2/community/users/:user_id/comments |
17 Comments
Do we have any insight on what OOTB integrations this will impact? Specifically Salesforce OOTB integration?
Hi Rogan,
OOTB integrations (built by Zendesk) will be auto-upgraded to use Cursor Pagination Model.
Hi,
Do time based incremental export considered OBP or CBP? and does it get affected by this change?
reference: https://developer.zendesk.com/documentation/ticketing/managing-tickets/using-the-incremental-export-api/#time-based-incremental-exports
Hi Oonwattana,
Time based Incremental Export is a special case and not considered either OBP or CBP. The new page 100 limit is not applicable to it.
You can export tickets using cursor-based exports or time-based exports. However, Zendesk strongly recommends using cursor-based exports for better performance.
Hi,
Thanks for the recommendation, but we will still be keeping with the Time based method.
The issue with cursor-based is that it gives out the next page path as code, e.g. https://{{subdomain}}.zendesk.com/api/v2/incremental/tickets/cursor.json?cursor=MTU3NjYxMzUzOS4wfHw0Njd8
This is making it very much difficult to troubleshooting in case of issues, or let's say that the service stops polling the ticket data, and want to restart the service, we would not know what was the time stamp that the service got stopped.
Hi Oonwattana,
We respect your method choice as it is still valid way to paginate data.
---
I would like to provide some extra information for your scenario. I hope you it could be helpful.
Unsure if you already know this, but the cursor value is a base64 string of {unix_time} and other relevant coded value used by Zendesk to paginate results in an optimal way.
For example, `MTU3NjYxMzUzOS4wfHw0Njd8` is base64Encoded value of `1576613539.0|...|` which in turn is `Tuesday, 17 December 2019 20:12:19` in human readable time.
If debugging is a concern, especially figuring out the timestamp, you may do that with the cursor model as well with this single extra decoding step when needed.
You can always use a mix of timed and cursor models. This will be handy to restart your export job after any issues. Referencing the docs -
Hope this helps.
Thanks for the update Sanjeev Mandalapu
I am also wondering if cursor based pagination is supporting ticket_events in incremental export?
https://developer.zendesk.com/api-reference/ticketing/ticket-management/incremental_exports/#incremental-ticket-event-export
From below doc, it says it only supports tickets/users, not ticket_events?
https://developer.zendesk.com/documentation/ticketing/managing-tickets/using-the-incremental-export-api/#cursor-based-incremental-exports
As of today, only Time Based Model is supported for the ticket_events.
We will update in the documentation when support for CBP model is made available.
Hi there,
Will this take effect in Zendesk Sandbox environments at the same time?
Thanks!
Rich
Hi there! Is Cursor Pagination available in list-tickets-from-a-view api?
Thanks in advance!
Hi Rich Herbert - Comcast HR,
Yes, the changes will be rolled out at the same time.
Hi Hossein Vahedi,
We are providing CBP Support for the Tickets View. The change is being rolled out and we will update the documentation once it is fully there.
Change:
Zendesk has extended the timeline by a week to August 22, 2023 UTC from August 15, 2023 to give full 3 months notice.
"offset pagination" explicitly gives the total count value, but "cursor pagination" makes it difficult to calculate the total count.
I would like to show what percentage is currently fetched when some API is performed sequentially fetching a few hundred pages. So the user can choose to wait or give up. Waiting without a promise only gives users pain.
However, "offset pagination" has a total count, so it is easy to calculate how far it has progressed, but "cursor pagination" makes this difficult or impossible.
For example user.json it gives api/v2/users/count.json but for other api the total count is often unknown.
Is there any way to improve this? Also, are there any plans to provide a "count" value in all "cursor pagination" methods?
Because of this total count, I can't easily turn it into "cursor pagination".
There are certain design criteria on the Cursor Model as stated in the documentation. Count is one of such criteria and you have to use the relevant endpoint's /count path to get the count you need.
Analysing the traffic we get, the product has identified the top endpoints and already provide count for -
Do you a specific endpoint that needs count ? What is the use case for your integration/app ?
Thank you.
hi. Sanjeev
Your team isn't listed above, but the article API also has new limits starting yesterday. That's why I looked for this update notice. But in the article API there is no /count path for the endpoint you mentioned.
https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/
If you have this, I'd be grateful if you let me know.
If your team hasn't made it yet, please make it soon.
Then I'm happy to switch to "cursor pagination" and ride.
Thanks. 고마워.
Thank you.
I will reach out to the Help Center teams and explore the option of providing count in the respective endpoints.
Please sign in to leave a comment.