Skip to main content

Pagination

Some endpoints return their results in pages. You read one page at a time, and each page tells you whether more data remains.

How pagination works​

A paginated endpoint returns one page of results. While more data remains, the response envelope carries a paginationToken next to the usual status, details and data fields:

{
"status": "success",
"details": null,
"data": [ ... ],
"paginationToken": "d7NZap54n1sNzFzozSs6CM7sbxzkkH34WtHoe5YC8M3guD9fG8HmeqdbgjxzFHLelFiv99yo04o16MFw1ArRyQ"
}

On the last page, the paginationToken field is absent.

Reading the next page​

To read the next page, send the same request again and add the paginationToken you received. Keep every other parameter unchanged. The platform rejects a token that does not match the parameters it was issued for with 400.

let token = null;
do {
const url = `/s360/v3/catalog/${salesChannelId}/events`
+ `?salesRule=ON_SALE&performanceDateFrom=2026-01-01T00:00:00Z`
+ (token ? `&paginationToken=${encodeURIComponent(token)}` : "");
const page = await get(url);
merge(page.data);
token = page.paginationToken;
} while (token);

On an endpoint that takes its parameters in the request body, send the token in the body with the other parameters.

Rules for clients​

  • Treat the pagination token as an opaque value. Do not attempt to decode it, build it or change it. Its structure can change at any time without notice.
  • Do not keep a pagination token for later use. If you wait too long to read the next page, there is a chance that the returned data may be stale.
  • There is no total count. The absence of paginationToken is the only sign that you have read all the data.
  • Page size is not guaranteed. Each endpoint decides how many results a page holds. A page can hold fewer results than the one before it. Some endpoints may let you set a maximum page size.
  • You cannot choose a start position. The only way to reach a page is to follow the tokens from the first page.
  • In some rare cases, a page can be empty and still carry a token. Continue to follow the token until it is absent.

Endpoints that use offset and limit​

Some endpoints still take offset and limit query parameters instead of paginationToken. These endpoints will soon move to the paginationToken mechanism.

  • offset: the position of the first result to return. Whether counting starts at 0 or at 1 depends on the endpoint and is given on its reference page, together with the default.
  • limit: the maximum number of results to return. The default and the maximum value are given on the reference page of each endpoint.

The reference page of each endpoint shows which of the two mechanisms it uses. Write your integration so that it can follow a paginationToken.

Extracting large datasets​

Extracting large datasets is not supported from web services: data extraction use cases should use webhook patterns or dedicated Data Analytics APIs.