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

# Pagination

> How list endpoints are paginated

List endpoints use **cursor pagination**. There are no page numbers and no total counts — this keeps list requests fast on large workspaces, where a `COUNT(*)` or deep `OFFSET` would be expensive.

## Response shape

Every list endpoint returns the same envelope:

```json theme={null}
{
  "data": [ ... ],
  "has_more": true,
  "next_cursor": "cD0yMDI2LTA3LTA0..."
}
```

<ResponseField name="data" type="array">
  The page of results.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether more results exist after this page.
</ResponseField>

<ResponseField name="next_cursor" type="string or null">
  An opaque cursor pointing at the next page. `null` when `has_more` is `false`.
</ResponseField>

## Fetching the next page

Pass the `next_cursor` value back as the `cursor` query parameter to fetch the following page:

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.audienceful.com/v2/people?cursor=cD0yMDI2LTA3LTA0...' \
  --header 'X-Api-Key: <your-api-key>'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.audienceful.com/v2/people"
  headers = {"X-Api-Key": "<your-api-key>"}
  params = {"cursor": "cD0yMDI2LTA3LTA0..."}

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.audienceful.com/v2/people?cursor=cD0yMDI2LTA3LTA0...",
    {
      method: "GET",
      headers: { "X-Api-Key": "<your-api-key>" },
    },
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

Keep following `next_cursor` until `has_more` is `false`.

## Page size

Control the number of items per page with the `page_size` query parameter. Each list endpoint has its own default and maximum — for example, contacts default to `100` and allow up to `500`.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.audienceful.com/v2/people?page_size=250' \
  --header 'X-Api-Key: <your-api-key>'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.audienceful.com/v2/people"
  headers = {"X-Api-Key": "<your-api-key>"}
  params = {"page_size": 250}

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.audienceful.com/v2/people?page_size=250",
    {
      method: "GET",
      headers: { "X-Api-Key": "<your-api-key>" },
    },
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>