PageToken

PageToken is an opaque string used in APIs to fetch subsequent pages of a collection. In cursor-based pagination, the server returns a page of results along with a pageToken (often nextPageToken) that encodes the position in the dataset. The client includes this token in the next request as a parameter, typically named pageToken or nextPageToken, to retrieve the following page. The initial request may omit the token or supply an empty value; the server then returns the first page and a token to continue.

Tokens are generally opaque to clients; they should not be interpreted or modified. They may encode a cursor, an item id, a timestamp, or internal state; the exact format is not guaranteed. The token is intended to be consumed by the server to resume listing from the correct position.

Security and reliability considerations include transmitting tokens over HTTPS, and accounting for token expiry or revocation. If the underlying data changes, a token may no longer reflect the correct next page; some APIs handle this by returning a fresh token or requiring a restart of pagination.

Semantics and differences: pageToken-based pagination contrasts with offset-based pagination that uses numeric pages and limits. Tokens can provide stable pagination in dynamic datasets where new items may be added or removed, whereas simple offsets can lead to skipped or duplicated items.

Common patterns: APIs such as Google’s use nextPageToken in responses and require a pageToken in subsequent requests. Some implementations expose related parameters like start or cursor. If there is no further data, a nextPageToken may be omitted or set to null.