Explaining Pagination Metadata in API Responses

When an API returns many items, it often sends them in separate responses. This is called pagination: the client requests one group of results at a time. The response may include metadata such as a cursor or links to other pages. It may also include a page-size value or a total count.

These fields help a client request more results, but each API defines what they mean and how to use them. Follow the endpoint’s documented rules, especially when deciding whether another page exists. A short page does not necessarily mean the results have ended, and a total count does not necessarily mean the client has retrieved every item.

Cursors and page links tell you how to continue

A cursor is a value the client sends back to the API to continue retrieving results. Some APIs use an opaque token, a value the client passes back without interpreting. Others use an object identifier as a position in an ordered list. For example, Stripe’s list endpoint uses object IDs with parameters for moving to the next or previous position.

Use the cursor as the endpoint documents. Do not decode it, create one yourself, or assume it works with different filters or sort settings. The API’s rules also determine how long a cursor remains valid. Google’s pagination guidance allows page tokens to expire, while expiration behavior in other services can differ.

A next link is a URL the client requests to retrieve a later page. The API can return it in the response body or in an HTTP Link header, a header format for describing links between web resources. When an endpoint supplies a next link, follow the complete URL rather than rebuilding it. For example, Microsoft Graph’s paging guidance tells clients to use the full @odata.nextLink value.

A previous link points to an earlier page. Use one when the endpoint provides it and documents its meaning. An API may omit it on the first page, and some APIs do not support backward navigation. The HTTP link standard defines how links and their relationships are represented, but it does not require every API to provide pagination links.

Treat a missing next link or cursor as an end-of-results signal only when the endpoint’s documentation says it means there are no more results. Absence can have other meanings. GitHub, for instance, documents cases where its Link header is omitted because pagination is unsupported or all results fit on one page.

Page size sets a request or limit

A page size is the requested number of items per response or the maximum the API allows. APIs use names such as limit, per_page, and page_size. The requested value does not guarantee that the response will contain that many items. The API can apply a default; it can also cap the value at a maximum or return fewer results.

Check whether the endpoint treats the value as a requested number, the number it will return, or a maximum. For example, GitHub documents that some endpoints reduce an oversized per_page value to the maximum. Google’s guidance also permits a response to contain fewer items than requested, including no items, even when more results remain.

For that reason, the number of items in a response is not a reliable way to decide whether to continue. Follow the documented cursor or next-link behavior. An empty page can still have a continuation value, so the client should not stop solely because the current response contains no items.

Total counts need a documented scope

A total count tells the client how many items match the endpoint’s criteria. It can help a client display progress or estimate remaining work, but its meaning depends on the endpoint. Check whether the count covers the same filters as the request and whether the API describes it as exact or estimated. Google’s guidance permits an estimated total when the API documents that limitation.

A total also does not necessarily appear on every page. Microsoft Graph documents that, for directory-resource queries using $count=true, @odata.count appears only on the first page. Use the count only for the items and pages the endpoint says it covers; do not rely on it alone to decide that pagination is complete.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com