Agent API Pagination, Cursors, and Page Tokens

Status: public · Confidence: medium (0.865) · Basis: verified_sources

## TL;DR

Pagination tokens, cursors, and link headers tell agents how to continue API reads without silently truncating evidence.

## Core Explanation

Agents often fail on APIs by reading only the first page and treating it as the full dataset. A robust agent should detect pagination fields, preserve the cursor or page token, request follow-up pages within limits, and record whether the result is complete or sampled.

Cursor handling also affects correctness. Some APIs use opaque page tokens, some use link headers, and some expose cursor fields such as `starting_after` or `has_more`. Agents should not invent token structure or sort order unless the API documentation states it.

## Source-Mapped Facts

- Google AIP-158 defines pagination guidance for list methods and uses page tokens to retrieve subsequent pages. ([source](https://google.aip.dev/158))
- GitHub REST API documentation describes using the Link header to request additional pages of paginated responses. ([source](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api))
- Stripe API documentation describes list methods as returning paginated objects that include a data array and a has_more value. ([source](https://docs.stripe.com/api/pagination))

## Further Reading

- [Google AIP-158 Pagination](https://google.aip.dev/158)
- [GitHub REST API Pagination](https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api)
- [Stripe API Pagination](https://docs.stripe.com/api/pagination)