> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarky.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Page through list endpoints with `page` and `page_size`

All list endpoints in the Clarky API return paginated results. Pagination is page-based — you ask for a specific page and a page size, and the response tells you how many pages there are in total.

## Query parameters

<ParamField query="page" type="integer" default="1">
  The 1-indexed page number to fetch.
</ParamField>

<ParamField query="page_size" type="integer" default="25">
  Number of items per page. **Maximum is 100.** Requests above the maximum return `validation_error`.
</ParamField>

## Response shape

Every list endpoint wraps results in `data` (the items for the current page) and `pagination` (metadata about the pagination state).

```json theme={null}
{
  "data": [
    { "id": "c_01HXYZ...", "first_name": "Ada" },
    { "id": "c_01HXYZ...", "first_name": "Grace" }
  ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total": 142,
    "total_pages": 6
  }
}
```

<ResponseField name="pagination.page" type="integer">
  The current page number (1-indexed).
</ResponseField>

<ResponseField name="pagination.page_size" type="integer">
  Number of items returned per page.
</ResponseField>

<ResponseField name="pagination.total" type="integer">
  Total number of items across every page.
</ResponseField>

<ResponseField name="pagination.total_pages" type="integer">
  Total number of pages. `total_pages` is `Math.ceil(total / page_size)`.
</ResponseField>

## Examples

### Fetch the first page

```bash theme={null}
curl "https://clarky.ai/api/v1/contacts?page=1&page_size=25" \
  -H "Authorization: Bearer ck_live_example"
```

### Fetch a larger page

```bash theme={null}
curl "https://clarky.ai/api/v1/contacts?page_size=100" \
  -H "Authorization: Bearer ck_live_example"
```

### Iterate every page

```javascript theme={null}
async function fetchAllContacts(apiKey) {
  const all = [];
  let page = 1;

  while (true) {
    const res = await fetch(
      `https://clarky.ai/api/v1/contacts?page=${page}&page_size=100`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );

    const { data, pagination } = await res.json();
    all.push(...data);

    if (page >= pagination.total_pages) break;
    page += 1;
  }

  return all;
}
```

<Tip>
  For large backfills, prefer `page_size=100` to minimize round-trips, and respect the [rate limits](/api-reference/rate-limits) by backing off when you see `429` responses.
</Tip>

## Endpoints that don't paginate

A small number of endpoints return collections without pagination because the result set is bounded — for example, [stages within a pipeline](/api-reference/pipelines#list-pipeline-stages). These return `{ "data": [...] }` with no `pagination` object. The shape is documented per-endpoint.

## Single-resource responses

For endpoints that return a single resource (e.g. `GET /contacts/{id}`), the response is just `{ "data": { ... } }` — no `pagination` object.

```json theme={null}
{
  "data": {
    "id": "c_01HXYZ...",
    "first_name": "Ada"
  }
}
```