Pagination

How list endpoints return large result sets.

List endpoints use one of three styles. Each endpoint’s reference page lists its query parameters.

Cursor pagination

Used by GET /v1/results, GET /result-webhooks/deliveries, GET /campaigns/{id}/api-logs and GET /credits/ledger.

Parameter	Meaning
limit	Page size.
cursor	Pass the previous response’s nextCursor to get the next page. Omit it for the first page.

The response contains items and nextCursor. When nextCursor is null there are no more pages.

# first page
curl "https://api.pineyard.ai/v1/results?limit=100" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

# next page
curl "https://api.pineyard.ai/v1/results?limit=100&cursor=3f6c1a2b-0000-4000-8000-000000000000" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Endpoint	Default limit	Max limit	Also returns
GET /v1/results	50	100
GET /result-webhooks/deliveries	30	100
GET /campaigns/{id}/api-logs	50	100	total (matching rows)
GET /credits/ledger	50	200	totalCount

Treat cursors as opaque strings and don’t build them yourself.

Offset pagination

Used by most other paginated lists, for example GET /calls, GET /campaigns/{id}/leads and GET /speech/calls.

Parameter	Meaning
limit	Page size (default 50, maximum 200 unless the endpoint says otherwise).
offset	Number of items to skip.

Increase offset by limit until a page comes back with fewer than limit items. Where the endpoint returns a total, you can also stop once offset + limit >= total.

Response shapes differ between endpoints. Some return a bare array, some wrap results with a total (for example { "items": [...], "total": 120 }), and GET /workflows/{id}/runs returns the total in the X-Total-Count header. Check the endpoint’s reference page.

GET /commerce/orders uses page (1-based) and limit instead of offset.

Unpaginated lists

Lists of configuration objects (agents, campaigns, phone numbers, voices, documents, dictionaries, templates, senders, workflows and similar) return every item in one response.

A few endpoints return a fixed number of the most recent items and cannot be paged: for example GET /whatsapp/messages (up to 200) and GET /campaigns/{id}/activity (the latest 50 calls).