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

# How to Paginate Results in the Honestly Export API

> The Honestly Export API uses offset-based pagination. Use limit and offset query parameters to page through large result sets efficiently.

The Honestly Export API uses offset-based pagination for all list endpoints, allowing you to retrieve large datasets in manageable chunks.

## How it works

All list endpoints accept two query parameters to control pagination:

* **`offset`** — The number of records to skip from the beginning of the list. Use this to advance through pages of results.
* **`limit`** — The maximum number of records to return per request. Note: some endpoints enforce an upper bound on `limit`; exceeding it returns a `400` error.

Every paginated response includes a `total_count` field at the top level. This tells you the total number of records available across all pages. You can determine whether more pages exist by checking whether `offset + limit < total_count`.

## Example

The examples below show how to retrieve the first and second pages of surveys using a page size of 200.

<CodeGroup>
  ```bash First page theme={null}
  curl "https://api.honestly.com/v1/surveys?limit=200&offset=0" \
    -H "X-Api-Key: YOUR_SECRET_API_KEY"
  ```

  ```bash Second page theme={null}
  curl "https://api.honestly.com/v1/surveys?limit=200&offset=200" \
    -H "X-Api-Key: YOUR_SECRET_API_KEY"
  ```

  ```json Example response theme={null}
  {
    "total_count": 450,
    "surveys": [
      {
        "id": 101,
        "name": { "en": "Q1 Engagement Survey", "de": "Engagement-Befragung Q1" }
      },
      {
        "id": 102,
        "name": { "en": "Onboarding Pulse", "de": "Onboarding-Puls" }
      }
    ]
  }
  ```
</CodeGroup>

In the response above, `total_count` is `450`. With a `limit` of `200` and an `offset` of `0`, the response contains records 1–200. Setting `offset=200` retrieves records 201–400, and `offset=400` retrieves the final 50 records.

## Fetching all records

Use a loop that increments the `offset` by `limit` on each iteration, stopping when the `offset` reaches or exceeds `total_count`.

```bash theme={null}
# Example shell loop
OFFSET=0
LIMIT=200
TOTAL=1  # start >0 to enter loop

while [ $OFFSET -lt $TOTAL ]; do
  RESPONSE=$(curl -s "https://api.honestly.com/v1/surveys?limit=$LIMIT&offset=$OFFSET" \
    -H "X-Api-Key: YOUR_SECRET_API_KEY")
  TOTAL=$(echo $RESPONSE | jq '.total_count')
  OFFSET=$((OFFSET + LIMIT))
done
```

<Warning>
  Some endpoints enforce an upper limit on the `limit` parameter. Sending a value above the maximum returns a `400 Bad Request` error. Check the specific endpoint's documentation for its limit constraints.
</Warning>