Pagination & Response Envelopes

List endpoints return an offset page: a data array and the matching collection total. They do not use cursors.

{
  "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000" } ],
  "total_count": 42
}

Query parameters

Parameter	Role
`page`	1-based page index. Default 1. Values below 1 are treated as 1.
`page_size`	Page length. Minimum 1, maximum 100, default 10. Also accepted as `page-size`. Values below 1 fall back to the default; values above 100 are capped at 100.
`order_by`	Field to sort by. When omitted, the endpoint uses its default order. Also accepted as `order-by`.
`ascending`	Sort direction. Default true. Parsed as a boolean (`true` / `false`).

Do not send starting_after, ending_before, or a page index together with a cursor. This API pages by page / page_size only.

Walking a collection

Call the list endpoint with an optional page_size (and order_by / ascending if you need a non-default sort).
If page * page_size < total_count (or the page came back full and total_count is larger than len(data)), request page + 1.
Repeat until the page is short or page * page_size >= total_count.

Results on a given page can shift when rows are inserted or deleted between requests. That is the offset-pagination tradeoff; do not treat a page index as a stable cursor.