Docs › API reference › Pagination
Paginate API lists with cursors, in order
How to page through lists with a cursor, which endpoints are paginated, and in what order they return items.
List endpoints that can grow long return one page at a time. You ask for a page with limit and cursor, and
each answer tells you the cursor for the next page.
Parameters and response
| Parameter | Meaning |
|---|---|
limit |
How many items you want. The default is 25. A value above 100 is lowered to 100. A value of 0 or less means the default |
cursor |
The nextCursor from the previous page. Leave it out for the first page |
The response is always the same shape:
nextCursor is null when there is nothing more. Treat the cursor as an opaque string: pass it back
unchanged. (Today it is a UUID, and a cursor that is not a UUID gets 400 invalid_request.)
{
"items": [],
"nextCursor": "0192a3b4-0000-7000-8000-000000000042"
}
Walk through every page
Stop when nextCursor is null.
Keep the same filters (status, channel, from, to) on every page of one walk. A cursor only continues the
list you started.
curl "https://omniposts.dev/v1/targets?limit=50" \
-H "Authorization: Bearer omniposts_..."
# then, with the nextCursor from that answer:
curl "https://omniposts.dev/v1/targets?limit=50&cursor=0192a3b4-0000-7000-8000-000000000042" \
-H "Authorization: Bearer omniposts_..."
Paginated endpoints
| Endpoint | Order, newest first |
|---|---|
GET /v1/groups |
By the post's time: scheduledFor, else createdAt. Ties by newest id |
GET /v1/targets |
By sent time: publishedAt, else the post's scheduledFor, else creation. Ties by newest id |
GET /v1/ideas |
Drafts, newest first. Discarded drafts are never listed |
GET /v1/metrics/summary |
Published results, by publishedAt |
GET /v1/webhooks/{id}/deliveries |
A webhook's delivery log, newest first |
These return everything in one answer, with no cursor: GET /v1/channels, GET /v1/providers,
GET /v1/api-keys, GET /v1/webhooks and GET /v1/settings/consents. They return { "items": [...] }
with no nextCursor.