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

# Pagination

> Walk collections with opaque cursors, limit, and Link headers.

List endpoints use opaque **cursor** pagination. Each page returns a
`pagination` object; you follow the cursor it gives you until there are no more
pages.

## The pagination object

Every collection response carries a `pagination` block:

```json theme={null}
{
  "data": [{ "id": "…", "platform": "instagram" }],
  "pagination": {
    "next_cursor": "eyJhIjoiYiJ9",
    "has_next": true,
    "limit": 50
  },
  "filters": { "platform": "instagram" }
}
```

<ResponseField name="next_cursor" type="string | null">
  Opaque token for the next page. Pass it back as the `cursor` query param. It is `null`
  on the final page.
</ResponseField>

<ResponseField name="has_next" type="boolean">
  `true` while more pages remain; `false` on the final page. Use this as your stop
  condition.
</ResponseField>

<ResponseField name="limit" type="integer">
  The page size in effect for this response.
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total matching rows, included only when you request it (see below).
</ResponseField>

## Request a page

<ParamField query="limit" type="integer" default="50">
  Number of items per page, `1`–`200`. A few endpoints cap it lower — `GET /search` and
  `GET /creators/top` allow `1`–`25` (default `10`). Each endpoint's reference page
  lists its exact range.
</ParamField>

<ParamField query="cursor" type="string">
  The previous response's `pagination.next_cursor`. Omit it to fetch the first page.
</ParamField>

<ParamField query="include_total" type="boolean" default="false">
  When `true`, the response adds `pagination.total_count`. This runs an extra `COUNT`
  query, so request it only when you need the total.
</ParamField>

```bash theme={null}
# First page
curl "https://api.creatoraudit.com/v2/accounts?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page
curl "https://api.creatoraudit.com/v2/accounts?limit=50&cursor=eyJhIjoiYiJ9" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Warning>
  A cursor is bound to the exact filter and sort combination it was issued for. Keep
  your filters and `order_by`/`order_direction` identical across pages — reusing a
  cursor under a different filter or sort returns `422`.
</Warning>

## Link headers

List responses also include an RFC 8288 `Link` header with `rel="first"` and,
when more pages exist, `rel="next"` — a ready-to-follow absolute URL:

```http theme={null}
Link: <https://api.creatoraudit.com/v2/accounts?limit=50>; rel="first",
      <https://api.creatoraudit.com/v2/accounts?limit=50&cursor=eyJhIjoiYiJ9>; rel="next"
```

Follow `rel="next"` if you prefer not to assemble URLs yourself; the absence of a
`next` link mirrors `has_next: false`.

## Fetch all pages

Loop while `has_next` is true, passing the previous `next_cursor` each time.

<CodeGroup>
  ```bash bash theme={null}
  #!/usr/bin/env bash
  set -euo pipefail
  BASE="https://api.creatoraudit.com/v2"
  CURSOR=""

  while :; do
    URL="$BASE/accounts?limit=200"
    [ -n "$CURSOR" ] && URL="$URL&cursor=$CURSOR"

    RESP=$(curl -s "$URL" -H "Authorization: Bearer $API_KEY")
    echo "$RESP" | jq -c '.data[]'

    HAS_NEXT=$(echo "$RESP" | jq -r '.pagination.has_next')
    [ "$HAS_NEXT" = "true" ] || break
    CURSOR=$(echo "$RESP" | jq -r '.pagination.next_cursor')
  done
  ```

  ```python python theme={null}
  import os
  import httpx

  BASE = "https://api.creatoraudit.com/v2"
  headers = {"Authorization": f"Bearer {os.environ['API_KEY']}"}


  def fetch_all(path: str, **params) -> list[dict]:
      items: list[dict] = []
      cursor: str | None = None
      with httpx.Client(base_url=BASE, headers=headers) as client:
          while True:
              query = {"limit": 200, **params}
              if cursor:
                  query["cursor"] = cursor
              body = client.get(path, params=query).raise_for_status().json()
              items.extend(body["data"])
              page = body["pagination"]
              if not page["has_next"]:
                  return items
              cursor = page["next_cursor"]


  accounts = fetch_all("/accounts", platform="instagram")
  ```
</CodeGroup>

Combine cursors with filters and sorting — see
[Filtering and sorting](/api-reference/filtering-and-sorting). For per-endpoint
parameters, see the [API reference](/api-reference/introduction). For the page-size
cap and the other ceilings around it, see [Limits & quotas](/limits-and-quotas).