# Pagination

List endpoints return one page of results and a cursor for the next page:

```json
{
  "data": [{ "id": "user_…" }, { "id": "user_…" }],
  "nextCursor": "eyJiaW5kaW5nIjoi…"
}
```

Request the next page by passing `nextCursor` as `cursor`. When `nextCursor` is `null`, there are no more results.

```sh
curl "https://optlo.com/api/v1/users?limit=100&cursor=eyJiaW5kaW5nIjoi…" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Page size

`limit` sets the maximum number of results per page, from 1 to 100. The default is 50. A page can contain fewer results than `limit` even when more remain; rely on `nextCursor`, not the page size, to decide whether to continue.

## Cursors

Cursors are opaque. Do not construct, parse, or modify them.

A cursor is bound to the request that produced it, including its filters. Keep the same query parameters, apart from `cursor` and `limit`, when requesting later pages. A cursor used with different filters, a different endpoint, or another workspace returns `400 invalid_cursor`.

## Ordering

- Users, conversations, and webhooks are ordered by creation time, newest first.
- Messages are ordered by their position in the conversation, newest first.
- Webhook deliveries are ordered newest first.
- [Events](/docs/api-reference/events/) are ordered by ingestion sequence, newest first by default, or oldest first with `order=asc`.

## Consistency

Pages are not a snapshot. Resources created or changed while you page through a list can appear on a later page, be skipped, or reflect newer values than earlier pages.

The conversation list reads an eventually consistent inbox replica, so a newly created or updated conversation can take a moment to appear in it or match its filters. Getting a single conversation or its messages reads authoritative storage.

To keep a copy of Optlo data in sync, combine an initial paged listing with [events](/docs/api-reference/events/) or [webhooks](/docs/api-reference/webhooks/) for later changes.
