A cursor is an opaque position marker that lets an API retrieve the next chunk of paged data. The server returns results with the next token, allowing consumers to continue until the token is empty. section 21.2 section 21.3.2
Use cursor responses carefully:
- Do not treat a partially full page as the end; page sizes are maximums, not exact sizes. section 21.3.2
- Continue when results are empty but the next token is nonempty; the server may have stopped searching at a time limit. section 21.3.2
- Keep token contents opaque; they can encode whatever state the server needs, such as serialized state or a limit and offset. section 21.3.2
Paging through a large attachment
A read request can carry an attachment ID, pageToken, and maxBytes. Each response returns a chunk, a field mask identifying the supplied fields, and nextPageToken. The consumer appends chunks and stops when the token is empty. section 21.3.4
Follow the request-and-response flow from the first page through subsequent cursor-based requests. section 21.2
