Pagination

Most list endpoints in this API paginate by page number and limit. A couple paginate by cursor instead. They're not interchangeable, so it's worth knowing which one you're dealing with before you write a loop that fetches "everything."

Offset-based (most endpoints)

This is the default: segments, tags, custom fields, webhooks, broadcasts, forms, all of it.

curl "https://api.peleka.io/api/v1/segments?page=1&limit=50" \
  -H "X-API-Key: pel_live_..."

{
  "data": [ { "id": "...", "name": "VIP customers" } ],
  "total": 213,
  "page": 1,
  "limit": 50,
  "totalPages": 5
}

Increment page until it exceeds totalPages, or just stop once data comes back shorter than limit. Default limit is 20 where unspecified; most endpoints cap it at 100.

Cursor-based (contacts, contact activity)

Contact lists and per-contact activity feeds use a cursor instead, because these are the two places a workspace is genuinely likely to have enough rows (tens of thousands of contacts, a long activity history) that counting totalPages up front gets expensive for no real benefit.

curl "https://api.peleka.io/api/v1/contacts?limit=50" \
  -H "X-API-Key: pel_live_..."

{
  "data": [ { "id": "...", "email": "[email protected]" } ],
  "nextCursor": "eyJpZCI6MTIzNDV9"
}

Pass nextCursor back as the cursor query param to get the next page:

curl "https://api.peleka.io/api/v1/contacts?limit=50&cursor=eyJpZCI6MTIzNDV9" \
  -H "X-API-Key: pel_live_..."

When nextCursor comes back null, you've reached the end. Don't try to jump to an arbitrary page or guess at a cursor value; treat it as an opaque token and only ever pass back what the API gave you.

Why two conventions

Short version: offset pagination is simpler to reason about and fine for the low-thousands of rows most of these resources hold; cursor pagination avoids the performance cliff that comes with OFFSET on a large, frequently-written table like contacts. If you're building against both contacts and, say, segments in the same integration, don't assume one pagination shape works for both — check the reference page for the endpoint you're calling.