---
title: Pagination
description: How to page through Soljio lists with cursors, the limits on page size, and the three pagination styles that different operations use.
---

Any operation that can return many records returns them one page at a time. You ask for a page size, Soljio returns that many records plus an opaque cursor, and you send the cursor back to get the next page. Cursors are strings. Never parse, build, or edit one.

Soljio uses three pagination styles, depending on the kind of operation. The operation's response schema in the [API reference](/api) tells you which one it uses.

## Resource lists

`GET` requests on `/v0/organizations`, `/v0/locations`, `/v0/programs`, `/v0/offerings`, `/v0/sessions`, `/v0/participants`, and `/v0/enrollments` take two query parameters:

| Parameter | Rules                                                           |
| --------- | --------------------------------------------------------------- |
| `limit`   | An integer from 1 to 100. The default is 25                     |
| `cursor`  | A cursor returned by the previous page, up to 16,384 characters |

The response includes `next_cursor`. It is `null` on the last page.

```bash
curl -sS "https://api.soljio.com/v0/programs?limit=100" \
  -H "Authorization: Bearer $SOLJIO_TOKEN"

curl -sS "https://api.soljio.com/v0/programs?limit=100&cursor=CURSOR_FROM_PREVIOUS_PAGE" \
  -H "Authorization: Bearer $SOLJIO_TOKEN"
```

Loop until `next_cursor` is `null`:

```js
const base = "https://api.soljio.com/v0/programs";
const headers = { Authorization: "Bearer " + process.env.SOLJIO_TOKEN };
const programs = [];
let cursor = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, { headers });
  if (!response.ok) throw new Error("Request failed: " + response.status);

  const page = await response.json();
  programs.push(...page.data);
  cursor = page.next_cursor;
} while (cursor);
```

:::warning[A page can be empty]
A page may contain no records and still return a non-null `next_cursor`. Keep going until `next_cursor` is `null` rather than stopping at the first empty page.
:::

Some rules to remember:

- Reuse a cursor only with the same school and the same resource. Pages are not a snapshot, so records added or changed while you page can appear or move.
- `limit` and `cursor` cannot be combined with an ID in a detail request such as `/v0/programs/PROGRAM_ID`. That returns `400`.
- `/v0/organizations` returns your school as a one-item list and takes no `cursor`.
- An invalid `limit` (for example `0`, `101`, or `abc`), a malformed cursor, a repeated parameter, or any other query-string parameter returns `400` with `invalid_request`.

## Filtered queries with `pagination_opts`

Many `POST /v0/queries/{operation}` operations take a `pagination_opts` object in the body:

```json
{
  "pagination_opts": { "cursor": null, "num_items": 25 }
}
```

`cursor` is required: send `null` for the first page. `num_items` is an integer from 1 to 100.

The names of the cursor fields in the response depend on the operation:

| Response fields | Used by | Continue until |
| --- | --- | --- |
| `has_more`, `next_cursor`, with the records in `rows` | The `search_` queries, such as `search_programs`, `search_offerings`, `search_participants`, and `search_enrollments` | `has_more` is `false` |
| `is_done`, `continue_cursor`, with the records in `page` | Listing and export queries, such as `export_data`, `get_report_rows`, `list_instructors`, and `list_notification_deliveries` | `is_done` is `true` |

Send the returned cursor back as `pagination_opts.cursor` together with the same filters. A cursor is tied to the school, the operation, and its filters. Reuse it only with the same ones, or the request can be rejected.

Listing and export responses can also include `split_cursor` and `page_status`. The contract declares these fields without describing them, so this guide does not rely on them.

```bash
curl -sS -X POST "https://api.soljio.com/v0/queries/search_programs" \
  -H "Authorization: Bearer $SOLJIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pagination_opts":{"cursor":null,"num_items":25}}'
```

## Operations with their own cursor field

A few queries paginate with a top-level `cursor` field instead of `pagination_opts`. For example, `list_audit_events` takes an optional `cursor` together with filters such as `action` and `actor`, and returns `continue_cursor` and `is_done`. `get_operations_queue` also takes an optional `cursor` and returns its paging state in a `pagination` object. A few others page one of several lists inside their response, using fields such as `inactive_next_cursor` or `archived_cursor`. These follow the same rule: send back the cursor you received, with the same filters.

## Troubleshooting

- **400 `invalid_request` on a follow-up page.** The cursor was changed, truncated, or used with different filters or on a different resource. Start again from the first page.
- **Missing or duplicate records between pages.** Pages are not a snapshot. If you need a consistent view, page quickly and deduplicate by `id`.
- **Hitting rate limits while paging.** Each page costs one request. Use the largest page size and follow [Rate limits](/developers/rate-limits).
