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
Bill Mattern
Hi Team,
I am checking our zendesk integration code and we are using time-based bookmarks combined with offset-based pagination under 10000 results (usually). From what I am reading this should be supported after the new limits are deployed. Is there a way to tell ahead of time in the response if the method we are using will no longer be supported?
Also, can someone confirm if the Zopim endpoints are also in scope for this upcoming change on May 20?
0
Sanjeev Mandalapu
Hi Bill,
Using OBP for results under 10k is allowed and would not be impacted by the rollout. However, we strongly recommend to switch to CBP. It is possible in the future that the limits will be further reduced from 10k to 1k. Cursor Model is very performant and recommended for most of the use cases, so please consider it if appropriate in your use case.
Also, Zopim is not impacted by this change.
1
James
@... I'm still seeing offset-based pagination only for the users.json: GET endpoint – I have no way of listing all records. Can you confirm this endpoint has cursor-based pagination?
0
Tony
check this article in our documentation. I believe it will be helpful for you.
Best,
0
James
Tony Can you email me? The documentation does not match the API response. There are no cursors in the v2/users.json response, only next_page param that uses offset-based pagination.
0
Radha
Hey,
I am using the endpoint api/v2/ticket_metrics.json to fetch ticket metrics. My goal is to retrieve metrics until the tickets are 7 days old, utilizing pagination. Initially, I used offset pagination, but due to its limitations, I switched to cursor pagination.
However, I am encountering issues with cursor pagination, as each API call takes between 17 to 30 seconds. Upon debugging, I discovered that the API response time is significantly higher with cursor pagination.
Could you please help me understand why this is happening? Is the increased response time due to the use of cursor pagination? How can I resolve this issue? It is crucial for me to reduce the API response time.
1
Sanjeev Mandalapu
Hi James,
Users does support Cursor Pagination. Cursor Pagination is invoked by passing the
page[size]
parameter. Have you changed your code to call the users endpoint with it?Cursor Pagination -
/api/v2/users.json?page[size]=100
0
Sanjeev Mandalapu
Hi Radha,
There should be no added latency when using Cursor pagination compared to Offset model. It is engineered to be better performant and responsive if not equal.
I request you to raise a ticket with Zendesk detailing your integration, subdomain, time of calls, the debugging logs and any other relevant information. We will be able to thoroughly investigate it from there.
0
Justina
Our Zendesk instance has experienced severe performance issues since May 23rd. From what we see in the browser console, in the tab Network, your Ticketing API results in constant errors for /api/v2/recipient_addresses.
Despite announcing it here, it looks like Zendesk does not offer the cursor-based pagination (CBP) for the /api/v2/recipient_addresses and still uses the deprecated Offset Pagination method, which constantly leads to ticket errors.
When we submit the ticket response, the deprecated Offset Pagination method used by Zendesk blocks ticket solving and results in the agent responses not going through. Even small get requests for a single comment last for 10s+.
When will you start using the cursor-based pagination (CBP) for the /api/v2/recipient_addresses?
0