Skip to content

Pagination

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

{
"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.

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

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

  • 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 are ordered by ingestion sequence, newest first by default, or oldest first with order=asc.

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 or webhooks for later changes.