---
title: "Pagination"
description: "How to read a long list in pages."
url: https://docs.roasos.com/concepts/pagination
---

# 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:

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

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

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

<Callout type="idea">
  Do not parse a cursor, and do not construct a cursor. The format can change. Send back only the value that you received.
</Callout>

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