> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How v1 list endpoints return results in pages with an opaque page token, and why a short page doesn't mean the end.

Every v1 list endpoint pages the same way, with an opaque page token.

1. Set the page size with `page_size`.
2. Read `next_page_token` from the response.
3. Send that value as `page_token` to get the next page.
4. Stop when `next_page_token` is missing or `null`.

```bash Fetch the first page theme={null}
curl -s 'https://api.lumos.com/v1/apps?page_size=50' \
  --header 'Authorization: Bearer lsk_your_token'
```

```json Response theme={null}
{
  "apps": [{ "id": "..." }],
  "next_page_token": "PjF-YWNtZQ=="
}
```

```bash Fetch the next page theme={null}
curl -s 'https://api.lumos.com/v1/apps?page_size=50&page_token=PjF-YWNtZQ%3D%3D' \
  --header 'Authorization: Bearer lsk_your_token'
```

## Page tokens

A page token is opaque. Don't decode it, build one by hand, or infer meaning from it. An empty,
malformed, or altered page token returns `400`, with `code` set to `pagination.invalid_page_token`.
The request doesn't silently restart at the first page. To get the first page,
omit `page_token`.

A page token works only with the endpoint and filters that produced it. Keep `page_size` and every filter the same on every
request until you reach the last page.

## Short and empty pages

A page can contain fewer items than your `page_size`, even when more items remain. A page can even
be empty while `next_page_token` is still set. Several endpoints do this, including
[List Workflows](https://docs.lumos.com/api-reference/v1/workflows/list-workflows.md),
[List Workflow Steps](https://docs.lumos.com/api-reference/v1/workflows/list-workflow-steps.md), and
[List Identity Events](https://docs.lumos.com/api-reference/v1/identity-events/list-identity-events.md). Stop only when
`next_page_token` is missing or `null`, never on a short or empty page.

```python theme={null}
# Correct: stop only when the token is gone.
params = {"page_size": 100}
while True:
    page = get("/v1/workflows", params=params)
    yield from page["workflows"]
    token = page.get("next_page_token")
    if not token:
        break
    params["page_token"] = token
```

```python theme={null}
# Wrong: exits early on the first short page.
if len(page["workflows"]) < 100:
    break
```

## Maximum page size

The maximum `page_size` varies by endpoint.

If you send a `page_size` above the endpoint's maximum, Lumos uses the maximum instead of
rejecting the request. A successful call doesn't tell you the maximum.

To find the exact maximum and default, read the `page_size` parameter in the reference for the
endpoint you call.