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

# Pagination

> Use cursor-based pagination to work through Caspen collection endpoints

## Overview

Caspen APIs use cursor-based pagination. Each paginated response includes `links.prev` and `links.next` entries with fully qualified URLs. When another page is unavailable, the corresponding link is `null`.

## Request parameters

| Name     | Required | Type    | Description                                                                                                                                |
| -------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `limit`  | No       | integer | Maximum number of records to return per page (1-100). If omitted, the endpoint uses its default page size (10 unless otherwise noted).     |
| `cursor` | No       | string  | Cursor token that identifies the page to fetch. Use the value embedded in the `links.next` or `links.prev` URL from the previous response. |

## Response structure

Every paginated response returns the resource collection plus a `links` object that guides you to neighbouring pages.

```json theme={null}
{
  "data": [
    { "id": "..." }
  ],
  "links": {
    "prev": null,
    "next": "https://api.caspen.com/v1/clients?cursor=eyJ0eXBlIjoiY3Vyc29yIiwgLi4u"
  }
}
```

* `links.prev`: URL for the previous page or `null` when you are at the beginning of the dataset.
* `links.next`: URL for the next page or `null` once you have reached the end.

## Fetching the next page

1. Request the first page, optionally setting `limit` to control page size.

```bash theme={null}
curl https://api.caspen.com/v1/clients \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
```

2. Read `links.next` from the response. If it is not `null`, issue another request using that URL verbatim.

```bash theme={null}
curl "https://api.caspen.com/v1/clients?cursor=eyJ0eXBlIjoiY3Vyc29yIiwgLi4u" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
```

Repeat this process until `links.next` becomes `null`.