Skip to content
FolioSign inStart your trial

Docs · Concepts

Pagination

How limit and cursor work, what meta tells you, and how to walk every page.

List operations take two query parameters:

ParameterMeaning
limitItems per page, 1 to 100 (the default is on the operation; teachings default to 25). A few public lists allow more.
cursorThe opaque meta.next_cursor from the previous page.

meta.has_next says whether another page exists, and meta.next_cursor is set only then. Cursors are opaque: do not build or parse them. A cursor Folio did not issue answers 400 invalid_argument.

curl -X GET "$FOLIO_API_URL/v1/teachings?limit=25&status=ready" \
  -H "Authorization: Bearer $FOLIO_API_KEY"
Response
{
  "status": true,
  "message": "teachings",
  "data": [{ "id": "tch_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012", "object": "teaching", "title": "Nothing can separate us", "status": "ready" }],
  "meta": { "request_id": "req_b337770ecebe03b03a88a8998b59263d", "has_next": true, "has_prev": false, "next_cursor": "eyJ0IjoiMjAyNi0xMS0wMVQxMDowMjoxMVoifQ", "total": 61 }
}

Fetch the next page by passing the cursor back, with the same filters:

curl -X GET "$FOLIO_API_URL/v1/teachings?limit=25&status=ready&cursor=eyJ0IjoiMjAyNi0xMS0wMVQxMDowMjoxMVoifQ" \
  -H "Authorization: Bearer $FOLIO_API_KEY"

Walking every page#

async function* all(path, headers) {
  let cursor = "";
  do {
    const url = `${process.env.FOLIO_API_URL}${path}${path.includes("?") ? "&" : "?"}limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`;
    const body = await (await fetch(url, { headers })).json();
    yield* body.data;
    cursor = body.meta.has_next ? body.meta.next_cursor : "";
  } while (cursor);
}

Things to know#

  • A page can hold fewer items than limit while has_next is true. This happens when items are filtered after the page is cut, as with unpublished notes. Keep following next_cursor until has_next is false.
  • Small lists (webhook endpoints, links, care alerts, subscribers) are paged over a bounded snapshot. Large collections page through the database.
  • meta.total is present on lists that know it, such as teachings.

Verified against API version 0.0.0-dev. Generated from the live OpenAPI document.