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:
| Parameter | Default | Meaning |
|---|---|---|
limit | 20 | How many records to return, from 1 to 100. |
cursor | none | The 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:
{
"data": [
{ "id": "item_gdwadfjn13zb7o5", "...": "..." },
{ "id": "item_2jzlbe8cm7kgfic", "...": "..." }
],
"total": 412,
"limit": 2,
"next_cursor": "eyJwb3NpdGlvbiI6eyJjcmVhdGVkQXQiOiIyMDIxLTAyLTI1VDIzOjIzOjI5LjAwMFoiLCJ1aWQiOiJpdXNoOTN4djN4cnN2MWMifSwiZmlsdGVycyI6Imw5Rnc0VlVPN2tyOCJ9"
}| Field | Meaning |
|---|---|
data | The records on this page. |
total | How many records match your filters, across all pages. |
limit | The page size applied to this response. |
next_cursor | Send 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.
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.
| List | Order |
|---|---|
| Items | Oldest created_at first. New items appear on the last page. |
| Inspections | Newest inspected_at first. Undated inspections come last. |
| An item's history | Newest 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.