# Paging and the cursor grammar

Every listing answers a page, never the whole set. A page is the same shape everywhere: `items` holds the records, `nextToken` the cursor for the next page. This guide is how to walk one, how to ask for less, and what the cursor promises.

## The shape

A listing such as [brands](/reference/brand/brands/) answers a page — [BrandPage](/types/BrandPage/) — with `items`, the records of this page in the listing's own order, and `nextToken`: a string when more may remain, `null` when the listing is complete. A filtered or sorted listing also answers `matchCount`, the exact size of the whole matched set; an unfiltered page leaves it `null`.

## Walking the pages

Ask for the first page with no cursor. If the answer's `nextToken` is not `null`, send the same call again with that value as its `nextToken` argument — exactly as you received it, never edited, never built by hand. Stop when `nextToken` comes back `null`. A page may hold fewer records than you asked for even when more pages remain, so only a `null` cursor means the end. Use `limit` to ask for smaller pages.

## What the cursor promises

A cursor is opaque and belongs to the listing that minted it: it is bound to your organization group, to the call, and to the filter and sort you gave. Replaying it under a different filter or sort is refused rather than answered wrongly, and a cursor from one listing means nothing to another. Keep the cursor and the call together.

## Filtering and sorting

Most listings take a `filter` and a `sort`. A filter is a list of clauses — the record matches when every clause matches, and a clause matches when the field matches any of its values (AND across clauses, OR within a clause) — at most 8 clauses, and at most 25 values in a clause. Each family declares which fields may be filtered and which operators they take: a text field takes `contains` and `begins_with`, a state or reference field `any_of`, a date `on`, `before`, `after` or `between`, a number or an amount `eq`, `lt`, `gt` or `between`, a yes-or-no field `is`. An unknown field or operator is refused by name, never silently ignored. Every listing's reference page shows one clause in the family's own terms.

A sort names one declared field and a direction. Records missing the fact trail in either direction, and ties resolve by id, so every order is total and pages are stable.

## Records that vanish between pages

Listings hide retired records as they go, so a page may come back short. Nothing is skipped: walk to the `null` cursor and you have seen every live record.