# Pagination

How list endpoints page with limit and cursor.


List endpoints take `limit` (default 25, maximum 100) and an opaque `cursor`, and return a page of results with the cursor for the next page:

```json
{
  "data": [ { "id": "..." } ],
  "next_cursor": "eyJ..."
}
```

## Parameters

- `limit` is the page size. The default is 25 and the maximum is 100.
- `cursor` is the `next_cursor` value from the previous page. Treat it as opaque: do not build or edit one.

## Walk through all pages

```bash
curl "https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/people?limit=100" \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

If `next_cursor` is not `null`, request the next page with it:

```bash
curl "https://kleiobase.com/api/v1/workspaces/WORKSPACE_ID/people?limit=100&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer kb_live_YOUR_KEY"
```

Stop when `next_cursor` is `null`.

## Things to know

- A page can be shorter than `limit` and still have a `next_cursor`. Matches, for example, drop suggestions that involve a person in Trash. Keep following `next_cursor` until it is `null`.
- A few endpoints are not paginated: workspaces, a person's timeline and conflicts. They return everything and `next_cursor` is always `null`.
- A bad `limit` or `cursor` returns `422 validation_failed`.

Canonical: https://kleiobase.com/developers/docs/pagination