# Pagination

> Offset-based pagination for list endpoints, and the exceptions to the standard shape.

Source: https://tickos.dev/docs/pagination

Most list endpoints use offset-based pagination with the limit and offset query parameters and return the items in data plus a pagination object.

| Parameter | Default | Description |
|---|---|---|
| limit | 50 (20 on some endpoints, see below) | Maximum number of items to return. Capped at 100. |
| offset | 0 | Number of items to skip. |

```bash
curl 'https://api.tickos.dev/v1/tickets?limit=20&offset=40' \
  -H 'Authorization: Bearer sk_your_api_key'
```

## List response

```json
{
  "data": [{ "id": "...", "subject": "..." }],
  "pagination": {
    "limit": 20,
    "offset": 40,
    "total": 128
  }
}
```

total is the number of items matching your filters, so there are more pages while offset + limit < total.

Endpoints that follow this standard shape (limit default 50): GET /v1/tickets, GET /v1/tickets/{id}/messages, GET /v1/customers, GET /v1/contact-groups and GET /v1/contact-groups/{id}/members.

## Endpoints with a different shape

Some list endpoints use a different default, a different collection key or no pagination at all:

| Endpoint | Params | Response shape |
|---|---|---|
| GET /v1/inboxes | page (default 1), limit (default 50) | { data, pagination: { page, limit, total, pages } } |
| GET /v1/campaigns | limit (default 20), offset | { campaigns, pagination: { total, limit, offset } } |
| GET /v1/campaigns/unsubscribed | limit (default 50), offset | { unsubscribed, pagination: { total, limit, offset } } |
| GET /v1/surveys | limit (default 50), offset | { surveys, pagination: { limit, offset, total } } |
| GET /v1/changelog | limit (default 20), offset | { data, pagination: { limit, offset, total } } |
| GET /v1/automations | limit (default 20), offset | { data, pagination: { limit, offset, total } } |
| GET /v1/automations/{id}/enrollments | limit (default 20), offset | { data, count, limit, offset } |
| GET /v1/emails/scheduled | limit (default 50), offset | { data, total, limit, offset } |
| GET /v1/connections | None (returns all) | { data, meta: { total } } |
| GET /v1/keys | None (returns all) | { data, meta: { total } } |
| GET /v1/tags | None (returns all; optional inbox_id filter) | { data, count } |
| GET /v1/users | None (returns all) | { data, count } |
| GET /v1/tickets/{id}/tags | None (returns all) | { data, count } |
| GET /v1/messages/{id}/attachments | None (returns all) | { attachments, count } |

> **Tip:** For incremental syncs, use updated_after (ISO 8601) on GET /v1/tickets and created_after on GET /v1/tickets/{id}/messages instead of walking every page.