Pagination

A list endpoint gives its results in pages. One cursor rule serves every list of the API.

How pages work

Each response contains a meta object:

{
  "data": [ ... ],
  "meta": {
    "has_more": true,
    "cursor": "eyJ2IjoyLCJjcmVhdGVkX2F0..."
  }
}

To read the next page, send that cursor value in your next request:

curl "https://api.roasos.com/v1/jobs?limit=20&cursor=CURSOR_FROM_LAST_RESPONSE" \
  -H "Authorization: Bearer roasos_sk_..."

If has_more is false, you are at the end of the list.

Options

limit — the number of items in one page. The range is 1 to 100. The default value is 20.
cursor — the value of meta.cursor from the last response.

A cursor that roasOS cannot read is a 400 invalid_cursor. Request the first page again.

Do not parse a cursor, and do not construct a cursor. The format can change. Send back only the value that you received.

The lists that page

Endpoint	Holds
`GET /v1/jobs`	every job of the workspace
`GET /v1/generations`	the older generation records
`GET /v1/scenes`	your saved scenes
`GET /v1/avatars`	your saved avatars
`GET /v1/products`	your products
`GET /v1/voices`	your cloned voices
`GET /v1/skills`	your saved skills
`GET /v1/memory/pins`	the facts you pinned
`GET /v1/discover/items`	the roasOS library of example ads
`GET /v1/account/usage`	one line for each charge
`GET /v1/account/ledger`	the reservations, the captures and the refunds

Two list doors take no cursor. GET /v1/jobs/{id}/events and GET /v1/agent-runs/{id}/events answer with the whole timeline of one run, in order. A job holds eight lifecycle events at most. An agent run answers with 500 events at most.

How pages work

Options

The lists that page

On this page