Pagination

The Direct Web Services APIs includes several endpoints that return large datasets. For performance reasons, where large datasets are returned, the API does not return all records in a single response object.

Instead, results are divided into smaller, more manageable chunks ("pages"), where each page contains a limited number of records. After the initial call to the endpoint, the API consumer or client can request subsequent pages until the entire dataset has been retrieved.

This guide explains:

• The pagination method used.
• The settings that control pagination.
• The inputs required for the initial request to the API.
• The inputs required for subsequent requests to the API.
• How to identify the end of the dataset.

Cursor-Based Pagination

Direct Web Services APIs use cursor-based pagination to paginate through large datasets. Cursor-based pagination tells the API to return "n items after this specific item." The "cursor" is an identifier or token that the API uses to identify the "specific item".

For example, if the page size is 50, after fetching the first page (items 1–50 in a sorted list of results), the cursor points to the 50th item — the last item received. The next request tells the API to retrieve the next 50 items that come after this 50th item in the sorted list.

Direct Web Services APIs use Base64-encoded JSON tokens to point to the last item of the current page. Both forwards and backwards navigation is supported.

Pagination Settings

Pagination is controlled by the following request inputs:

Sort Settings

Cursor-based pagination depends on a consistent ordering of your data. If you change the sort order between requests, the cursor becomes meaningless.

Each API has default sort settings. Where configuration of sort settings is supported, ensure the same settings are applied in each request.

Information about sort options can be found in the documentation for individual APIs.

Initial Request

In the initial request, specify:

• The number of records to return per page.
• Sort settings (where supported). See Sort Settings for more information.

"pagination": {
  "pageSize": 25
}

The token to retrieve the next page of records is returned in the response metadata, along with the total count of records found.

"metadata": {
  "paginationTokenNext": "CN7aARoJKQDABEyTAQAAGgY6BHNpbGMaDDoKMHAwMDAwdDJ5aiIMOgowUDAwMDBUMllK",
  "totalCount": 1809,
  "requestId": "e7b7bfdf-076c-4668-a613-08794a375094",
  "time": "2026-01-30T10:00:20.2684413Z"
}

Subsequent Requests

To request the next page, call the endpoint again and pass the token returned in response to the previous request as the paginationTokenNext value.

"pagination": {
  "pageSize": 25,
  "paginationTokenNext": "CN7aARoJKQDABEyTAQAAGgY6BHNpbGMaDDoKMHAwMDAwdDJ5aiIMOgowUDAwMDBUMllK"
}

Tokens that allow you to page forward (paginationTokenNext) or backwards (paginationTokenPrevious) are returned.

"metadata": {
  "paginationTokenNext": "CN7aARoJKQDABEyTAQAAGgY6BHNpbGMaDDoKMHAwMDAwdDJ5aiIMOgowUDAwMDBUMllK",
  "paginationTokenPrevious": "CIWmBxoJKQDcgxOaAQAAGhQ6EmFtcGxpdHVkZSBzdXJnaWNhbBoMOgowcDAwMDE2N3J1Igw6CjBQMDAwMTY3UlU=",
  "totalCount": 1809,
  "requestId": "e7b7bfdf-076c-4668-a613-08794a375094",
  "time": "2026-01-30T10:00:20.2684413Z"
}

End of the Dataset

When the response does not contain a paginationTokenNext value, it indicates that you have reached the end of the dataset.

"metadata": {
  "paginationTokenPrevious": "CN7aARoJKQDABEyTAQAAGgY6BHNpbGMaDDoKMHAwMDAwdDJ5aiIMOgowUDAwMDBUMllK",
  "totalCount": 1809,
  "requestId": "e7b7bfdf-076c-4668-a613-08794a375094",
  "time": "2026-01-30T10:00:20.2684413Z"
}

Best Practices

• Keep sort order consistent between requests.
• Keep filters the same between pages. Otherwise, items may disappear or reappear between pages.