Data pagination

DingTalk OpenAPI supports two pagination methods. Different APIs may adopt different pagination mechanisms. Choose the appropriate pagination mode based on the specific API documentation and business scenario to improve data retrieval efficiency, reduce server-side load, and ensure system stability.

​

Applicable scope and permissions

This document applies to the following types of apps:

• Internal app: Apps developed by an organization for use only within that organization.
• Third-party enterprise app: Apps developed by ISVs (Independent Software Vendors) and made available for multiple organizations to install and use.
• Third-party personal app: Apps developed by solution providers for individual DingTalk users.

​

Permissions

Before calling any DingTalk OpenAPI, make sure the app has the required API permissions. In the DingTalk Open Platform console, complete the following steps:

1. Go to the details page of the target app.
2. Click Basic information > Credentials and basic information.
3. In the “Manage permissions” section, add the required API permissions (such as “Read contacts” or “Get event list”).

Reference: How to apply for API permissions

​

Authentication prerequisites

Before calling any API, obtain a valid access_token for authentication and permission verification.

• Use App Key / App Secret or Client ID / Client Secret to obtain an access_token.
• The access_token is typically valid for 7,200 seconds. Cache it and refresh it periodically.
• An invalid or expired access_token causes the API to return error code 40001 or 40014.

Reference: How to call APIs

​

Method 1: nextToken pagination

Use nextToken as a query credential to read data continuously. The first request does not require a nextToken. For subsequent requests, copy the nextToken value from the previous response into the current request to retrieve the next batch of data.

​

Request flow

• For the first request, do not pass nextToken. The server returns the first batch of data along with a nextToken value.
• For subsequent requests, pass the nextToken value from the previous response as a query parameter to retrieve the next page.
• When the response no longer contains a nextToken, all data has been retrieved.

Example: GET /v1.0/edu/grades/{identifier}/classes?nextToken=bGFzdD0xMTExMExMSZdGhlcnBhcmFtPXh4eCYuLi4u&maxResults=20

​

Key terms

• nextToken: An opaque string credential generated by the server that identifies the context position of the current query. The client must pass it through as-is and must not parse or modify it.
• maxResults: The maximum number of entries suggested by the client. This is not an exact value. The actual number returned may be less, depending on server-side limits or the amount of remaining data.

​

Notes

• The maxResults parameter limits the maximum number of records returned per request. Do not exceed 500 to avoid response latency.
• Deep pagination may degrade performance. Combine pagination with a time window filter to reduce data volume.

​

Recommended scenarios

• Data synchronization tasks (such as contacts sync or log retrieval)
• Large dataset exports
• Scenarios with high data integrity requirements

​

Method 2: pageSize pagination

This method uses traditional pagination logic and is suitable for front-end list APIs (such as user lists, department lists, and approval forms). It controls data loading using page numbers and page sizes.

​

Request flow

• For the first request, set pageNumber=1 and specify the number of records per page using pageSize.
• For each subsequent request, increment pageNumber until the returned data volume is less than pageSize, which typically indicates the last page.

​

Notes

• Start the first call with pageNumber=1 and increment the page number for each subsequent call.
• This method is not suitable for high-frequency retrieval of large amounts of data, as it may affect server-side performance.

​

Key terms

• pageNumber: The current page number of the request, starting from 1.
• pageSize: The number of entries returned per page. The recommended range is 10 to 200.

​

Recommended scenarios

• Integration with front-end pagination controls (such as table pagination)
• Display of small-scale static data
• Page-by-page browsing triggered by user actions

​

Recommendations and best practices

​

Selection guidance

• Incremental sync APIs (such as event subscription pulls or change log retrieval): Use the nextToken method to ensure that data does not repeat or get missed.
• List display APIs (such as employee lists or approval form lists): Use the pageSize method for easy integration with front-end pagination components.

​

Best practices summary

• For incremental sync APIs, use Method 1: nextToken pagination to ensure that data does not repeat or get missed.
• For list display APIs, use Method 2: pageSize pagination for easy integration with front-end pagination controls.
• Implement an automatic retry mechanism on the client. If a request fails due to an invalid nextToken, fall back to the initial request and retrieve the data again.
• Avoid excessively large maxResults or pageSize values. The recommended range is 10 to 200 to balance network transmission efficiency and response speed.