Pagination
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 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.
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:
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);
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.
limitandcursorcannot be combined with an ID in a detail request such as/v0/programs/PROGRAM_ID. That returns400./v0/organizationsreturns your school as a one-item list and takes nocursor.- An invalid
limit(for example0,101, orabc), a malformed cursor, a repeated parameter, or any other query-string parameter returns400withinvalid_request.
Filtered queries with pagination_opts
Many POST /v0/queries/{operation} operations take a pagination_opts object in the body:
{
"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.
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_requeston 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.