Scannable Docs
Get started

Pagination

Page through list endpoints with limit and cursor.

Every list endpoint returns one page at a time, and pages by cursor. Choose the page with two query parameters:

ParameterDefaultMeaning
limit20How many records to return, from 1 to 100.
cursornoneThe next_cursor of the previous page. Leave it out for the first page.

A limit above 100, below 1 or not a whole number returns 400 with code: "validation_failed". It is not lowered for you. See Errors.

The lists that page this way are folders, labels, items, item history, inspections, checklists, inspection frequencies, members, teams and a team's members. None of them takes offset: sending it returns 400.

The list envelope

Every list has the same shape:

GET /v1/items?limit=2
{
  "data": [
    { "id": "item_gdwadfjn13zb7o5", "...": "..." },
    { "id": "item_2jzlbe8cm7kgfic", "...": "..." }
  ],
  "total": 412,
  "limit": 2,
  "next_cursor": "eyJwb3NpdGlvbiI6eyJjcmVhdGVkQXQiOiIyMDIxLTAyLTI1VDIzOjIzOjI5LjAwMFoiLCJ1aWQiOiJpdXNoOTN4djN4cnN2MWMifSwiZmlsdGVycyI6Imw5Rnc0VlVPN2tyOCJ9"
}
FieldMeaning
dataThe records on this page.
totalHow many records match your filters, across all pages.
limitThe page size applied to this response.
next_cursorSend it as cursor for the next page. null on the last page.

Treat a cursor as an opaque string. Don't build one or change it. It is one unbroken token, so copy all of it.

Fetch every page

Send each page's next_cursor as cursor, with the same filters, until it is null. A cursor remembers the filters that issued it, and refuses others with 400, so you can't mix two lists by mistake. limit and include may change between pages.

list-all.mjs
async function listAll(path, params = {}) {
  const records = [];
  let cursor = null;

  do {
    const url = new URL(path, 'https://api.scannable.io');
    url.search = new URLSearchParams({ ...params, limit: '100' });
    if (cursor) {
      url.searchParams.set('cursor', cursor);
    }

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.SCANNABLE_API_KEY}` },
    });
    if (!response.ok) {
      const { error } = await response.json();
      throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
    }

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

  return records;
}

const failed = await listAll('/v1/items', { status: 'not_safe_failed' });

At 100 records a page, the rate limit of 60 requests a minute reads 6,000 records a minute from one list. See Rate limits.

Order and changing data

A cursor marks a position in the list, not a page number. Records added or removed while you page don't make you skip or repeat the others.

ListOrder
ItemsOldest created_at first. New items appear on the last page.
InspectionsNewest inspected_at first. Undated inspections come last.
An item's historyNewest first.

Use a cursor only on the list that issued it. A cursor the list can't read returns 400, with cursor in fields.

Skip unchanged pages

Every page comes with an ETag header. Send it back as If-None-Match when you read the same page again. If nothing on the page has changed, you get 304 Not Modified with no body, so keep what you have.

A 304 saves downloading the page, not the request: it still counts against the rate limit.

On this page