Announced on | Rolling out on (staggered) |
May 22, 2023 |
May 20, 2024 - Non EU regions - COMPLETED September 09, 2024 - EU region - COMPLETED |
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 May 20, 2024, 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 May 20, 2024. 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.
We're ensuring a seamless transition for all users by staggering the rollout, with the EU region accounts changes scheduled for release in three months' time - September 09, 2024.
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 |
Java |
>= v0.24.1 supports Cursor Pagination. Refer to the release tag here. Using Maven |
PHP |
>= 3.0.01 supports Cursor Pagination composer require zendesk/zendesk_api_client_php:^3.0.1 Refer to the upgrade guide. |
MS BI Connector |
A new and improved Zendesk Data Connector is now provided with capability to fetch records > 1000 rows and uses Cursor Model for faster data retrieval. Please refer to the Migration guide on how to use the latest connector. |
Go Lang |
>=v0.18.0 Please refer to the Upgrade guide |
C# |
>= 7.0.7 supports Cursor Pagination Refer to the README section on how use cursor based pagination |
Endpoints with CBP Capability
Product | Endpoint |
Ticketing | /api/v2/activities |
Ticketing | /api/v2/audit_logs |
Ticketing | /api/v2/automations |
Ticketing | /api/v2/automations/active |
Ticketing | /api/v2/brands |
Ticketing | /api/v2/custom_objects/:custom_object_key/fields |
Ticketing | /api/v2/custom_objects/:custom_object_key/records |
Ticketing | /api/v2/custom_objects/:custom_object_key/records/autocomplete |
Ticketing | /api/v2/custom_objects/:custom_object_key/records/search |
Ticketing | /api/v2/custom_objects/:custom_object_key/triggers |
Ticketing | /api/v2/custom_objects/:custom_object_key/triggers/active |
Ticketing | /api/v2/deleted_tickets |
Ticketing | /api/v2/deleted_users |
Ticketing | /api/v2/deletion_schedules |
Ticketing | /api/v2/dynamic_content/items |
Ticketing | /api/v2/dynamic_content/items/:item_id/variants |
Ticketing | /api/v2/end_users/:end_user_id/identities |
Ticketing | /api/v2/group_memberships |
Ticketing | /api/v2/group_memberships/assignable |
Ticketing | /api/v2/groups |
Ticketing | /api/v2/groups/:group_id/memberships |
Ticketing | /api/v2/groups/:group_id/memberships/assignable |
Ticketing | /api/v2/groups/:group_id/users |
Ticketing | /api/v2/groups/assignable |
Ticketing | /api/v2/groups/available_agents |
Ticketing | /api/v2/incremental/ticket_metric_events |
Ticketing | /api/v2/job_statuses |
Ticketing | /api/v2/macros |
Ticketing | /api/v2/macros/active |
Ticketing | /api/v2/macros/groups |
Ticketing | /api/v2/organization_fields |
Ticketing | /api/v2/organization_memberships |
Ticketing | /api/v2/organization_subscriptions |
Ticketing | /api/v2/organizations |
Ticketing | /api/v2/organizations/:organization_id/organization_memberships |
Ticketing | /api/v2/organizations/:organization_id/requests |
Ticketing | /api/v2/organizations/:organization_id/subscriptions |
Ticketing | /api/v2/organizations/:organization_id/tickets |
Ticketing | /api/v2/organizations/:organization_id/users |
Ticketing | /api/v2/problems |
Ticketing | /api/v2/recipient_addresses |
Ticketing | /api/v2/requests |
Ticketing | /api/v2/requests/:request_id/comments |
Ticketing | /api/v2/requests/ccd |
Ticketing | /api/v2/requests/open |
Ticketing | /api/v2/requests/solved |
Ticketing | /api/v2/satisfaction_ratings |
Ticketing | /api/v2/search/export |
Ticketing | /api/v2/sessions |
Ticketing | /api/v2/skips |
Ticketing | /api/v2/suspended_tickets |
Ticketing | /api/v2/tags |
Ticketing | /api/v2/:target_type/:target_id/relationship_fields/:field_id/:source_type |
Ticketing | /api/v2/ticket_audits |
Ticketing | /api/v2/ticket_content_pins |
Ticketing | /api/v2/ticket_fields |
Ticketing | /api/v2/ticket_fields/:ticket_field_id/options |
Ticketing | /api/v2/ticket_metrics |
Ticketing | /api/v2/tickets |
Ticketing | /api/v2/tickets/:ticket_id/audits |
Ticketing | /api/v2/tickets/:ticket_id/comments |
Ticketing | /api/v2/tickets/:ticket_id/incidents |
Ticketing | /api/v2/tickets/:ticket_id/skips |
Ticketing | /api/v2/trigger_categories |
Ticketing | /api/v2/triggers |
Ticketing | /api/v2/triggers/active |
Ticketing | /api/v2/user_fields |
Ticketing | /api/v2/user_fields/:user_field_id/options |
Ticketing | /api/v2/users |
Ticketing | /api/v2/users/:user_id/group_memberships |
Ticketing | /api/v2/users/:user_id/groups |
Ticketing | /api/v2/users/:user_id/identities |
Ticketing | /api/v2/users/:user_id/organization_memberships |
Ticketing | /api/v2/users/:user_id/organization_subscriptions |
Ticketing | /api/v2/users/:user_id/organizations |
Ticketing | /api/v2/users/:user_id/requests |
Ticketing | /api/v2/users/:user_id/sessions |
Ticketing | /api/v2/users/:user_id/skips |
Ticketing | /api/v2/users/:user_id/tickets/assigned |
Ticketing | /api/v2/users/:user_id/tickets/ccd |
Ticketing | /api/v2/users/:user_id/tickets/requested |
Ticketing | /api/v2/views |
Ticketing | /api/v2/views/:id/execute |
Ticketing | /api/v2/views/:id/tickets |
Product | Endpoint |
Help Center | /hc/api/v2/incremental/articles |
Help Center | /hc/api/v2/articles/attachments/:id |
Help Center | /hc/api/v2/articles/labels |
Help Center | /hc/api/v2/articles/labels/:id |
Help Center | /hc/api/v2/articles/:article_id/translations/missing |
Help Center | /hc/api/v2/articles/:article_id/translations |
Help Center | /hc/api/v2/articles/:article_id/translations/:id |
Help Center | /hc/api/v2/categories/:category_id/translations/missing |
Help Center | /hc/api/v2/categories/:category_id/translations |
Help Center | /hc/api/v2/categories/:category_id/translations/:id |
Help Center | /hc/api/v2/user_segments/applicable |
Help Center | /hc/api/v2/user_segments/:user_segment_id/sections |
Help Center | /hc/api/v2/user_segments/:user_segment_id/topics |
Help Center | /hc/api/v2/user_segments |
Help Center | /hc/api/v2/user_segments/:id |
Help Center | /hc/api/v2/sections/:section_id/translations/missing |
Help Center | /hc/api/v2/sections/:section_id/translations |
Help Center | /hc/api/v2/sections/:section_id/translations/:id |
Help Center | /hc/api/v2(/:locale)/articles/:article_id/attachments/:scope |
Help Center | /hc/api/v2(/:locale)/articles/:article_id/attachments |
Help Center | /hc/api/v2(/:locale)/articles/:article_id/attachments/:id |
Help Center | /hc/api/v2(/:locale)/articles/:article_id/labels |
Help Center | /hc/api/v2(/:locale)/articles/:article_id/comments/:comment_id/votes |
Help Center | /hc/api/v2(/:locale)/articles/:article_id/comments |
Help Center | /hc/api/v2(/:locale)/articles/:article_id/comments/:id |
Help Center | /hc/api/v2(/:locale)/articles/:article_id/votes |
Help Center | /hc/api/v2(/:locale)/articles/:article_id/subscriptions |
Help Center | /hc/api/v2(/:locale)/articles/:article_id/subscriptions/:id |
Help Center | /hc/api/v2(/:locale)/articles |
Help Center | /hc/api/v2(/:locale)/articles/:id |
Help Center | /hc/api/v2(/:locale)/categories/:category_id/articles |
Help Center | /hc/api/v2(/:locale)/categories/:category_id/sections |
Help Center | /hc/api/v2(/:locale)/categories |
Help Center | /hc/api/v2(/:locale)/categories/:id |
Help Center | /hc/api/v2(/:locale)/sections/:section_id/articles |
Help Center | /hc/api/v2(/:locale)/sections/:section_id/subscriptions |
Help Center | /hc/api/v2(/:locale)/sections/:section_id/subscriptions/:id |
Help Center | /hc/api/v2(/:locale)/sections |
Help Center | /hc/api/v2(/:locale)/sections/:id |
Help Center | /hc/api/v2/community/posts/:post_id/comments/:comment_id/votes |
Help Center | /hc/api/v2/community/posts/:post_id/comments |
Help Center | /hc/api/v2/community/posts/:post_id/comments/:id |
Help Center | /hc/api/v2/community/posts/:post_id/subscriptions |
Help Center | /hc/api/v2/community/posts/:post_id/subscriptions/:id |
Help Center | /hc/api/v2/community/posts/:post_id/votes |
Help Center | /hc/api/v2/community/posts |
Help Center | /hc/api/v2/community/posts/:id |
Help Center | /hc/api/v2/community/topics/:topic_id/subscriptions |
Help Center | /hc/api/v2/community/topics/:topic_id/subscriptions/:id |
Help Center | /hc/api/v2/community/topics/:topic_id/posts |
Help Center | /hc/api/v2/community/topics |
Help Center | /hc/api/v2/community/topics/:id |
Help Center | /hc/api/v2/community/users/:user_id/posts |
Help Center | /hc/api/v2/community/users/:user_id/comments |
Help Center | /hc/api/v2/users/:user_id/articles |
Help Center | /hc/api/v2/users/:user_id/subscriptions |
Help Center | /hc/api/v2/users/:user_id/user_subscriptions |
Help Center | /hc/api/v2/users/:user_id/comments |
Help Center | /hc/api/v2/users/:user_id/votes |
Help Center | /hc/api/v2/users/:user_id/user_segments |
Help Center | /hc/api/v2/votes |
Help Center | /hc/api/v2/votes/:id |
39 comments
Clik Rogan
Do we have any insight on what OOTB integrations this will impact? Specifically Salesforce OOTB integration?
0
Sanjeev Mandalapu
Hi Rogan,
OOTB integrations (built by Zendesk) will be auto-upgraded to use Cursor Pagination Model.
0
Tanawat Oonwattana
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
0
Sanjeev Mandalapu
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.
0
Tanawat Oonwattana
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.
0
Sanjeev Mandalapu
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.
0
Tanawat Oonwattana
Thanks for the update @...
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
0
Sanjeev Mandalapu
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.
0
Herbert, Rich
Hi there,
Will this take effect in Zendesk Sandbox environments at the same time?
Thanks!
Rich
0
Hossein Vahedi
Hi there! Is Cursor Pagination available in list-tickets-from-a-view api?
Thanks in advance!
0
Sanjeev Mandalapu
Hi Herbert, Rich,
Yes, the changes will be rolled out at the same time.
0
Sanjeev Mandalapu
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.
0
Sanjeev Mandalapu
Change:
Zendesk has extended the timeline by a week to August 22, 2023 UTC from August 15, 2023 to give full 3 months notice.
0
Sanjeev Mandalapu
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.
0
Sanjeev Mandalapu
Thank you.
I will reach out to the Help Center teams and explore the option of providing count in the respective endpoints.
0
Abhinay Pandey
Hi,
I'm using /ticket_forms endpoint to fetch zendesk ticket forms but I did not find the /ticket_forms API listed in above mentioned "Endpoints with CBP Capability" list. Does this API support cursor pagination or just offset pagination for now.
Also, while using the offset pagination I'm always getting the same result set even after passing per_page and page parameters to the request param. Is there anything which I missed out.
I would really appreciate any help.
example request : https://{{subdomain}}.zendesk.com/api/v2/ticket_forms.json?per_page=5&page=1
thanks
0
David
Hello!
I’m happy to help. The /ticket_forms endpoint is not listed in the “Endpoints with CBP Capability” list because it does not support CBP pagination. Instead, it supports cursor pagination and offset 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.
Regarding your issue with offset pagination, it is possible that the page parameter is not being passed correctly. You can try using the next_page URL returned in the response to fetch the next set of results.
-2
Zachary Drake
I just got an email notification that our Zendesk is using the offset-based pagination and might be affected. Is there some way I can get more information about where we might be using this? Much of our Zendesk implementation was done before I started working for my current employer, so I don't know off the top of my head where we might be using this. Is there a way to learn which API or component we are using triggered this email warning?
7
AAQ Creations
Hello,
We've received an email notification regarding our Zendesk account's current use of OBP and the requirement to upgrade to an SDK version that utilizes CBP. What are the potential risks if we choose not to proceed with this upgrade? Our website predates my tenure, making it challenging to determine the impact on our API and which specific components of our site might be significantly affected. Could we please obtain more detailed information on this matter? Thank you for your assistance.
3
Walter
Hi @...,
It seems like not all of the endpoints listed in this article support CBP.
For example:
still returns responses based on OBP (at least on our instance).
I tried https://[XXXXXXXXXXX].zendesk.com/api/v2/ticket_fields/[XXXXXXXXXX]/options?page[size]=100
I was expecting to see the new response structure.
{
"custom_field_options": [],
}
However, I got a response with the same old structure:
{
"custom_field_options": [],
"next_page": XXXXXXXXXXXXX,
"previous_page": XXXXXXXXXXXXX,
"count": 225
}
Can you please help to confirm? I am not able to proceed with updating things until I know when all of the endpoints listed in this documents will be updated.
Thanks.
0
Sanjeev Mandalapu
Hi Walter,
Thank you for bringing this up.
I can confirm that the sub-resource "options" on "ticket fields" is not providing a cursor pagination response even when proper cursor parameters are sent in the request params.
The team is working on the root cause and a fix. I will update here once it is done/ready, also you are copied on the issue ticket.
0
Walter
Hi @...,
Thank you for looking into this.
0
Walter
Hi Abhinay Pandey,
Regarding your question:
I don't believe the ticket forms endpoint will support cursor pagination. The maximum number of ticket forms per instance is 300. See https://support.zendesk.com/hc/en-us/articles/4408846520858-Creating-multiple-ticket-forms
As stated above:
Furthermore, the API documentation for the ticket forms endpoint makes no mention of pagination. See https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_forms/#list-ticket-forms:~:text=%7D-,List%20Ticket%20Forms,-GET%20/api/v2
I've tried the per_page parameter on this endpoint and can confirm (on our instance) that the per_page parameter has no effect.
How many ticket forms does your instance have? And why do you want to limit it to 5 per page?
0
TJ
In the same boat as some others.. received an email "Upgrade your SDK libraries to avoid upcoming API rate limits" and "Our records indicate that you use at least one available SDK."
Would be great if you could tell me what we're using... because I have no idea where to begin to look. We're primarily using 3rd party tools.
1
Walter
Hi TJ,
Maybe you can start by:
This may give you a clue as to where the requests are coming from.
If you're using 3rd party tools, they are most likely using the API to create requests. You may want to contact each of the developers of those 3rd party tools to confirm that they are working to update their code.
0
Sanjeev Mandalapu
Hi Walter,
Thank you for the wait. The changes have been deployed and the /api/v2/ticket_fields/:ticket_field_id/options now supports Cursor Model.
1
Sanjeev Mandalapu
Hi @Zachary Drake,
Please raise a ticket using your account. Our Advocacy team will be able to assist on individual account related traffic/usage queries.
0
AdamB
Hello,
Is it safe to assume that using the Search->find() or ../api/v2/search.json?query={search_string} with page as part of the query params will not be impacted by this change? Especially if the search_string limits the results to under 10,000?
0
Walter
Hi AdamB ,
Yes, it appears that the search endpoint only supports offset pagination.
https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/#pagination
1
Sanjeev Mandalapu
Hi Adam,
Search endpoint results are limited to 1000 records or page 100 (with page size 10). So, they wont be impacted by this change.
1