Pagination
Overview
A listing returns one page at a time. When there is more to read, the response carries a next_token; send it back unchanged to get the next page, and stop when a response comes back without one.
That one rule holds on every listing, whatever it filters and however full its pages are, so it is the only test of "have I reached the end" worth writing.
How it works
The shape
A listing takes limit and next_token as query parameters and answers with items and, when more remain, next_token:
{ "items": [ { "…": "…" } ], "next_token": "…"}GET /repositories/{repo_id}/merge-requests?status=open&limit=50GET /repositories/{repo_id}/merge-requests?status=open&limit=50&next_token=…Send the same filters with every page. A token marks a position in one particular ordering of one particular result, and it means nothing with different filters attached.
A token is a position, not a page number
The token records where the last page stopped — the last row's place in the ordering — and the next page starts after it. Treat it as opaque: do not parse it, build one, or store it as anything but a string to send back.
Because it is a position rather than an offset, the list can change while you read it. A row created while you page does not push everything along by one, so you neither see a row twice nor skip one because something new arrived. Most listings are ordered newest first, and each listing's reference says what it orders by.
How many per page
limit sets the page size. Each listing states its own default and maximum in the API reference; most default to 20 and take up to 100.
Short pages
Most listings apply their filters — and the check on whether you can see each row — before they cut a page, so a page shorter than limit usually means the end. A few filter after reading, the audit log among them, and can return a short page, or an empty one, that still carries a token. The rule from the overview covers both: keep going while there is a token.
The listings that page differently
| Listing | How it pages |
|---|---|
Search — /search, and a group's or repository's search | next_token, but the position is in order of relevance rather than time |
| The audit log, invoices, limit-increase requests, a group's packages, TODO markers, the users in an organization | cursor in the request and next_cursor in the response — the same rule, with different names |
| A directory listing or a diff | page and limit, numbered from zero — what sits at a commit never changes, so a page number always names the same rows |
A few short listings, such as your top repositories, take limit alone and return one answer.
From the CLI
On a listing that pages by next_token, --all follows the token for you and merges every page's items into one result, up to 100 pages. Without it you get one page, its next_token is shown, and --next-token asks for the page after.
gitmoap mr list --repo-id acme/api --status open --all --output jsonRelated
- Listing isolationwhy the rows on a page depend on who is reading
- Searchranked results, and paging through them
- Audit loga listing whose pages can be short before the end
- Cachingwhy paging inside a commit is safe to cache