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 answers a page — 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.