Pagination - Synthesys Docs

Page through list endpoints with limit and offset, and see which routes work differently.

Most list routes use limit and offset.

Parameter	Type	Default	Rules
`limit`	integer	`50`	Maximum results to return, from 1 to 100.
`offset`	integer	`0`	Results to skip, from 0 to 1,000,000.

Request

curl "https://backend.synthesys.app/api/v1/contacts?limit=25&offset=50" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

The results are in data, and the page details are in pagination.

JSON

{
  "success": true,
  "data": [],
  "pagination": {
    "total": 240,
    "limit": 25,
    "offset": 50
  }
}

You've reached the end when offset + limit is at least total.

Fetch every page

offset=0
while :; do
  page=$(curl -s "https://backend.synthesys.app/api/v1/contacts?limit=100&offset=$offset" \
    -H "SYNTH_API_KEY: YOUR_API_KEY")
  echo "$page" | jq -c '.data[]'
  total=$(echo "$page" | jq '.pagination.total')
  offset=$((offset + 100))
  [ "$offset" -ge "$total" ] && break
done

Routes with standard pagination

These routes accept limit and offset, and return an accurate pagination.total:

GET /v1/agents
GET /v1/voices, where limit defaults to 100
GET /v1/contacts
GET /v1/campaigns
GET /v1/conversations
GET /v1/phone-numbers
GET /v1/knowledge-bases
GET /v1/knowledge-bases/{id}/entries
GET /v1/audiences
GET /v1/audiences/{id}/members
GET /v1/wallet/transactions

Routes that differ

Route	How it differs
`GET /v1/call-logs`	Uses `page` and `limit` instead of `offset`. See below.
`GET /v1/recordings`	Uses `page` and `limit` instead of `offset`. See below.
`GET /v1/analytics/agents`	Accepts `limit` from 1 to 50, default 10, and no `offset`. Returns no `pagination` object.
`GET /v1/agents/{id}/post-call-webhook/deliveries`	Returns the 10 most recent deliveries, with no paging parameters.
`GET /v1/follow-up-sequences`	Has no paging parameters or `pagination` object.

Call logs and recordings use pages

GET /v1/call-logs and GET /v1/recordings take page, from 1 to 1,000,000, and limit, which defaults to 50 with a maximum of 100. Results are newest first. Call logs with no start time come last.

cURL

curl "https://backend.synthesys.app/api/v1/call-logs?page=2&limit=25" \
  -H "SYNTH_API_KEY: YOUR_API_KEY"

JSON

{
  "success": true,
  "data": [],
  "pagination": {
    "total": 240,
    "page": 2,
    "limit": 25,
    "totalPages": 10
  }
}

Stop when page reaches totalPages. totalPages is 1 when there are no results.