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

# Pagination

Most list endpoints return a page of results and a token for the next page.

```json
{
  "items": [],
  "next_page_token": "",
  "prev_page_token": null
}
```

## Pagination loop

```mermaid
flowchart LR
  A([Start]) --> B[Request first page<br />limit=50]
  B --> C{next_page_token?}
  C -- empty / null --> D([Done])
  C -- present --> E[Request next page<br />page_token=...]
  E --> C
```

## Walk through pages

#### Request a page size

Use `limit` when the endpoint supports it.

```bash
curl "https://api.taigabilling.com/api/encounters/v4?limit=50" \
  -H "Authorization: Bearer $TAIGA_API_KEY"
```

#### Request the next page

Pass the returned `next_page_token` as `page_token`.

```bash
curl "https://api.taigabilling.com/api/encounters/v4?limit=50&page_token=$NEXT_PAGE_TOKEN" \
  -H "Authorization: Bearer $TAIGA_API_KEY"
```

#### Stop when the token is empty

Continue until `next_page_token` is empty or missing.

> **Don't rely on item counts.**
>
> Taiga enforces billing-provider NPI scope on list responses. Because filtering can happen after an upstream page is read, a page may contain fewer items than the requested limit. Use `next_page_token`, not item count, to decide whether more data may exist.

## Recommended loop

**`paginate.ts`**

```ts title="paginate.ts"
let pageToken: string | undefined;

do {
  const url = new URL("https://api.taigabilling.com/api/encounters/v4");
  url.searchParams.set("limit", "50");

  if (pageToken) {
    url.searchParams.set("page_token", pageToken);
  }

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${process.env.TAIGA_API_KEY}`,
    },
  });

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  const page = await response.json();

  for (const item of page.items ?? []) {
    // Process item.
  }

  pageToken = page.next_page_token || undefined;
} while (pageToken);
```