Skip to main content
Every list endpoint in the SDK uses cursor-based pagination through the shared types in sdk/shared/v1/pagination.proto. There is no offset parameter, anywhere.

Request

Response

List requests carry page_size and page_token directly as top-level fields (not nested under a pagination object). Responses similarly expose a top-level next_page_token. When it’s empty, you have reached the end.

Iterating

Why cursors

  • No skipped or duplicated records when the catalog changes mid-scan. Offsets shift when items are inserted/deleted; cursors don’t.
  • Stable performance. Server-side cursor lookups are O(1) regardless of page depth.
  • Token opacity. The token encodes server-internal state (sort key, snapshot ID, etc.). Don’t parse it; don’t reuse a token across endpoints.

Tips

  • Pick the largest page_size (up to 100) you can render — fewer round-trips, lower rate-limit pressure.
  • Tokens are tied to the originating request shape. If you change query, filters, or sort order, start from an empty token.
  • Tokens are short-lived. Treat 24 hours as a soft cap — if you persist a token longer, expect to restart pagination on stale-token errors.