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)

The maximum page size is 100 items. Requests for limit > 100 will be capped at 100.

Response Format

Paginated responses include a meta object with pagination details:

{
  "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

cURL - First Page

curl "https://app.demeterrr.com/api/v1/contacts?page=1&limit=25" \
  -H "X-API-Key: dem_your_key_here"

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

Use reasonable page sizes

Start with limit=50. Only increase if you’re processing data in batches and can handle larger responses.

Cache when possible

If data doesn’t change frequently, cache responses to reduce API calls.

Handle edge cases

Always check totalPages before requesting the next page. The last page may have fewer items than perPage.

Implement retry logic

Network errors can occur during multi-page fetches. Implement exponential backoff for retries.

Combining with Filters

You can combine pagination with filtering parameters:

# 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

Contacts API

Explore the Contacts API

Responses API

Explore the Responses API