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

# Handle Pagination

> Learn how to paginate search results effectively

Some operations return multiple pages of results, especially searches. This quick guide explains how to handle pagination effectively.

## Pagination Headers

Each response includes headers to help you navigate:

<ParamField body="X-Pagination-Next" type="string">
  Full URL to fetch the next page — **always use this URL as-is** for reliable pagination. Contains the cursor for cursor-based pagination.
</ParamField>

<ParamField body="X-Pagination-Previous" type="string">
  Full URL to fetch the previous page — **use this URL as-is** for reliable pagination
</ParamField>

## Pagination Parameters

<ParamField body="cursor" type="string">
  Cursor value for cursor-based pagination. **Always obtain this from the `X-Pagination-Next` response header** — do not construct cursor values manually. Cursors expire after **24 hours**; if expired, restart pagination from the beginning.
</ParamField>

<ParamField body="page_size" type="number">
  Maximum number of items per page (read-only, varies by operation)
</ParamField>

<ParamField body="page" type="number" deprecated>
  Page number to retrieve. **Removed as of January 15th, 2026** — use cursor-based pagination instead.
</ParamField>

## How to Paginate

<Tip>
  **Best practice:** Always follow the `X-Pagination-Next` header URL as-is. Stop when it's no longer present — you've reached the last page.
</Tip>

* Extract the cursor from the `X-Pagination-Next` response header
* Pass it as the `cursor` query parameter (or simply use the full URL from the header)
* Cursors are valid for **24 hours** — after that, you must restart from the beginning

### Pagination Example

<Steps>
  <Step title="1. Make the initial request">
    Start fetching the first page of results (no cursor needed).

    ```bash theme={null}
    curl -i --request GET \
      --url 'https://api.captaindata.com/v1/people/search?query=(keywords%3Aceo)' \
      --header 'X-API-Key: <your-api-key>'
    ```
  </Step>

  <Step title="2. Check the response headers">
    Examine the response headers to find pagination info:

    * `X-Pagination-Next`: URL for next page (includes cursor) or absent if last page
    * `X-Pagination-Previous`: URL for previous page or absent if first page
  </Step>

  <Step title="3. Fetch the next page">
    Use the full URL from `X-Pagination-Next`:

    ```bash theme={null}
    curl -i --request GET \
      --url 'https://api.captaindata.com/v1/people/search?query=(keywords%3Aceo)&cursor=eyJwYWdlIjoyLCJza...' \
      --header 'X-API-Key: <your-api-key>'
    ```
  </Step>

  <Step title="4. Continue until done">
    Repeat until the `X-Pagination-Next` header is **no longer present**, meaning you've reached the last page.
  </Step>
</Steps>

<Warning>
  Cursors expire after **24 hours**. If you receive an error indicating an invalid or expired cursor, you must restart pagination from the beginning (without a cursor).
</Warning>