Pagination | CAIL Health

List endpoints in the CAIL Health API use cursor pagination. Cursors are opaque, stable across inserts, and safe to pass back unchanged.

Request

Query parameter	Type	Default	Notes
`cursor`	string	omitted	Opaque cursor returned by the previous page. Omit on the first request.
`limit`	integer	endpoint default	The maximum number of items to return. Each endpoint documents its maximum.

1 {
2   "items": [/* resource objects */],
3   "nextCursor": "opaque-base64-string",
4   "total": 1234
5 }

Field	Notes
`items`	The resources on this page, in the documented sort order for the endpoint.
`nextCursor`	Opaque cursor to pass to the next request. Omitted or `null` when the current page is the last.
`total`	Total number of items matching the query. Some endpoints omit this where it is expensive to compute; the endpoint documents this behavior.

Stable. Cursors encode a position in the sort, not an offset. Inserts during paging do not cause items to be skipped or duplicated.
Opaque. Callers must not parse, decode, or modify cursors. Cursor format is not part of the public contract and may change.
Bounded. A cursor is only valid for the endpoint and query that produced it. Reusing a cursor across endpoints or after changing query parameters produces undefined behavior.

A typical client loop:

Request the first page with limit set to the page size you want.
Render items.
If nextCursor is present, request the next page with cursor=<nextCursor>. Otherwise, stop.