Skip to content
Soljio Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.
  • 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:

{
  "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_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.

Was this page helpful?