Pagination & Responses

By Orqestra · Published September 2, 2026

The envelope

Successful responses share one shape. List endpoints add meta.

{
  "success": true,
  "data": [ ... ],
  "meta": { "total": 1284, "page": 1, "limit": 50, "totalPages": 26 }
}

Read your values out of data rather than off the top level, so adding a sibling field later does not break your client.

Paging

Parameter	Default	Notes
`page`	`1`	1-indexed.
`limit`	`50`	Capped at 200. A larger value is silently reduced — it is not an error.

Because the cap is silent, do not assume a single large request returned everything. Drive your loop from meta.totalPages:

page=1
while : ; do
  resp=$(curl -s "https://orqestra.id/api/v2/contacts?page=$page&limit=200" \
    -H "Authorization: Bearer $ORQESTRA_TOKEN")
  echo "$resp" | jq -r '.data[] | .id'
  [ "$page" -ge "$(echo "$resp" | jq -r '.meta.totalPages')" ] && break
  page=$((page + 1))
done

Paging a changing list

Paging is offset-based, so a contact created while you are halfway through can shift rows between pages. For a consistent snapshot of a large set, prefer GET /contacts/export, which produces a CSV in one pass.