A page token is an opaque cursor that lets an API resume a previously started iteration of results. The server returns a nextPageToken with one response; the client supplies that value as pageToken in the next request. This pattern divides large collections or resources into manageable pages instead of requiring one oversized response. section 21.0 section 21.2 section 21.7
Follow the request-and-response flow from the initial page through subsequent page-token requests until the server returns no next token. section 21.2
Use page tokens according to these rules:
- Treat the token as opaque. Its contents belong to the API server and may encode whatever state is needed to continue, such as a serialized cursor or position information. section 21.3.2
- Stop when nextPageToken is empty or absent, not merely when the current results list is empty. An empty result can still accompany a nonempty token when the server found no results before its search limit. section 21.3.2 section 21.7
- Pair pageToken with maxPageSize. The requested size is a maximum, so the server can return before filling a page when continuing the search would take too long. section 21.3 section 21.7
Paging chat rooms
Request: ListChatRoomsRequest { pageToken: "", maxPageSize: 50 }. Response: ListChatRoomsResponse { results: [ChatRoom, ...], nextPageToken: "opaque-value" }. Send "opaque-value" as pageToken on the next request. When the response contains no nextPageToken, stop requesting pages. section 21.3 section 21.7
