> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cail.health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cail.health/_mcp/server.

# Pagination

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. |

## Response

```json
{
  "items": [/* resource objects */],
  "nextCursor": "opaque-base64-string",
  "total": 1234
}
```

| 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. |

## Properties

* **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.

## Iterating to the end

A typical client loop:

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