> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pineyard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
# 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`.

<Note>
  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.
</Note>

`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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.