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

# Pagination

> How to paginate through large result sets

## Overview

List endpoints that return multiple items are paginated to improve performance. The API uses **page-based pagination** with consistent metadata across all endpoints.

## Request Parameters

All list endpoints support these query parameters:

| Parameter | Type    | Default | Description                           |
| --------- | ------- | ------- | ------------------------------------- |
| `page`    | integer | `1`     | Page number to retrieve (starts at 1) |
| `limit`   | integer | `50`    | Number of items per page (max: 100)   |

<Note>
  The maximum page size is **100 items**. Requests for `limit > 100` will be capped at 100.
</Note>

## Response Format

Paginated responses include a `meta` object with pagination details:

```json theme={null}
{
  "data": [
    { ... },
    { ... }
  ],
  "meta": {
    "page": 1,
    "perPage": 50,
    "total": 247,
    "totalPages": 5
  }
}
```

### Meta Fields

| Field        | Type    | Description                            |
| ------------ | ------- | -------------------------------------- |
| `page`       | integer | Current page number                    |
| `perPage`    | integer | Items per page (as requested)          |
| `total`      | integer | Total number of items across all pages |
| `totalPages` | integer | Total number of pages                  |

## Example Requests

<CodeGroup>
  ```bash cURL - First Page theme={null}
  curl "https://app.demeterrr.com/api/v1/contacts?page=1&limit=25" \
    -H "X-API-Key: dem_your_key_here"
  ```

  ```bash cURL - Specific Page theme={null}
  curl "https://app.demeterrr.com/api/v1/contacts?page=3&limit=25" \
    -H "X-API-Key: dem_your_key_here"
  ```

  ```javascript JavaScript - Fetch All Pages theme={null}
  const apiKey = 'dem_your_key_here';
  const baseUrl = 'https://app.demeterrr.com/api/v1';

  async function fetchAllContacts() {
    let allContacts = [];
    let page = 1;
    let hasMore = true;

    while (hasMore) {
      const response = await fetch(`${baseUrl}/contacts?page=${page}&limit=100`, {
        headers: { 'X-API-Key': apiKey }
      });

      const result = await response.json();
      allContacts.push(...result.data);

      hasMore = page < result.meta.totalPages;
      page++;
    }

    return allContacts;
  }
  ```

  ```python Python - Fetch All Pages theme={null}
  import requests

  api_key = 'dem_your_key_here'
  base_url = 'https://app.demeterrr.com/api/v1'
  headers = {'X-API-Key': api_key}

  def fetch_all_contacts():
      all_contacts = []
      page = 1
      has_more = True

      while has_more:
          response = requests.get(
              f'{base_url}/contacts',
              headers=headers,
              params={'page': page, 'limit': 100}
          )
          result = response.json()
          all_contacts.extend(result['data'])

          has_more = page < result['meta']['totalPages']
          page += 1

      return all_contacts
  ```
</CodeGroup>

## Paginated Endpoints

These endpoints support pagination:

* `GET /api/v1/contacts`
* `GET /api/v1/surveys`
* `GET /api/v1/sequences`
* `GET /api/v1/responses`
* `GET /api/v1/reviews`

## Best Practices

<CardGroup cols={2}>
  <Card title="Use reasonable page sizes" icon="gauge">
    Start with `limit=50`. Only increase if you're processing data in batches and can handle larger responses.
  </Card>

  <Card title="Cache when possible" icon="hard-drive">
    If data doesn't change frequently, cache responses to reduce API calls.
  </Card>

  <Card title="Handle edge cases" icon="triangle-exclamation">
    Always check `totalPages` before requesting the next page. The last page may have fewer items than `perPage`.
  </Card>

  <Card title="Implement retry logic" icon="rotate">
    Network errors can occur during multi-page fetches. Implement exponential backoff for retries.
  </Card>
</CardGroup>

## Combining with Filters

You can combine pagination with filtering parameters:

```bash theme={null}
# Get page 2 of contacts from a specific location
curl "https://app.demeterrr.com/api/v1/contacts?location_id=123&page=2&limit=50" \
  -H "X-API-Key: dem_your_key_here"
```

See individual endpoint documentation for available filter parameters.

## Next Steps

<CardGroup cols={2}>
  <Card title="Contacts API" icon="users" href="/api-reference/contacts/list">
    Explore the Contacts API
  </Card>

  <Card title="Responses API" icon="chart-line" href="/api-reference/responses/list">
    Explore the Responses API
  </Card>
</CardGroup>