Pagination

Collections are paged with an opaque cursor. There is no offset and no page number.

Shape

{
  "data": [ … ],
  "pagination": {
    "next_cursor": "101076",
    "has_more": true
  }
}

Paging through

Pass the previous response's next_cursor back as cursor. When has_more is false, next_cursor is absent and you are done.

Sequence

GET /v1/codes?limit=100
GET /v1/codes?limit=100&cursor=101076
GET /v1/codes?limit=100&cursor=102395

limit

Defaults to 50, maximum 200. A larger value is clamped rather than rejected, so asking for 1000 gives you 200 and not an error.

Why cursors and not offsets

An offset shifts when rows are inserted, so a paging client silently skips or repeats records while the data underneath it moves. A cursor is a position in a stable ordering, so each record appears exactly once however the pages fall.

Treat the cursor as opaque. It is currently derived from the sort key — for changes it carries both an effective date and a row id, because tens of thousands of changes can share 1 January and a date alone would lose rows at a page boundary — but that is an implementation detail and may change.