How to Paginate Results in the Honestly Export API

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.

curl "https://api.honestly.com/v1/surveys?limit=200&offset=0" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"

curl "https://api.honestly.com/v1/surveys?limit=200&offset=200" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"

{
  "total_count": 450,
  "surveys": [
    {
      "id": 101,
      "name": { "en": "Q1 Engagement Survey", "de": "Engagement-Befragung Q1" }
    },
    {
      "id": 102,
      "name": { "en": "Onboarding Pulse", "de": "Onboarding-Puls" }
    }
  ]
}

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.

# 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

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.

​How it works

​Example

​Fetching all records

How it works

Example

Fetching all records