nextToken

NextToken is a term used in API design to refer to a pagination token that enables cursor-based traversal of large result sets. It is typically an opaque string returned by a server in response to a paged query and supplied by the client in subsequent requests to retrieve the next page of results.

In practice, a client requests a page of items with a limit (page size). The server returns a subset of items and a nextToken value. The client then makes another request, including the nextToken, to continue from that point. If no nextToken is returned, there are no more results. The token encodes the server-side query state, without requiring the client to know internal details such as offsets.

Tokens are usually strings and are designed to be opaque to clients. They may be URL-safe, may expire after a period, and can incorporate guards against misuse. Because nextToken-based pagination is stateless for the server, it helps scale reads over large datasets and remains robust to concurrent data changes more effectively than offset-based pagination.

Common conventions include returning a field named nextToken or nextPageToken in the response, and accepting a corresponding parameter in the request. Some ecosystems use alternative names such as continuationToken or endCursor, but the underlying concept remains the same: a token that resumes a paged query.

Example (conceptual): GET /items?limit=50 returns {"items":[...], "nextToken":"abc123"}. A subsequent request uses ?nextToken=abc123 to fetch the next page. When the nextToken field is missing or null, the end of the dataset has been reached.