​
Overview

All list endpoints in the ProBeya REST API use cursor-based pagination. Unlike offset-based pagination, cursors provide stable results even when records are added or deleted between requests — critical for operational data that changes frequently.

​
How It Works

Every paginated response includes a meta object with pagination state:

FieldTypeDescription
cursorstring | nullOpaque cursor pointing to the last item in the current page. Pass this as the cursor query parameter to fetch the next page. null when there are no more results.
has_morebooleantrue if additional pages exist beyond the current result set.
limitnumberThe page size used for this request.

​
Query Parameters

ParameterTypeDefaultRangeDescription
cursorstring(none)—Cursor from a previous response to fetch the next page. Omit for the first request.
limitnumber501–200Number of records to return per page.

​
Example: Fetching Pages

​
First Request

Omit the cursor parameter to start from the beginning:

curl "https://acme.probeya.com/api/v1/items?boardId=brd_clx9xyz789&limit=25" \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

Response:

{
  "data": [
    { "id": "itm_001", "name": "5S audit — Zone A" },
    { "id": "itm_002", "name": "OEE deviation investigation" },
    // ... 23 more items
    { "id": "itm_025", "name": "Update SOP-42 revision 3" }
  ],
  "meta": {
    "cursor": "itm_025",
    "has_more": true,
    "limit": 25
  }
}

​
Next Page

Pass the cursor from the previous response to get the next page:

curl "https://acme.probeya.com/api/v1/items?boardId=brd_clx9xyz789&limit=25&cursor=itm_025" \
  -H "Authorization: Bearer probeya_sk_live_abc123..."

Response:

{
  "data": [
    { "id": "itm_026", "name": "Calibration schedule review" },
    // ... more items
    { "id": "itm_043", "name": "Batch record discrepancy" }
  ],
  "meta": {
    "cursor": "itm_043",
    "has_more": true,
    "limit": 25
  }
}

​
Last Page

When there are no more results, has_more is false and cursor is null:

{
  "data": [
    { "id": "itm_089", "name": "CAPA closure report" }
  ],
  "meta": {
    "cursor": null,
    "has_more": false,
    "limit": 25
  }
}

​
Fetching All Records

To iterate through every record in a collection, loop until has_more is false:

async function fetchAllItems(boardId) {
  const items = [];
  let cursor = undefined;

  do {
    const params = new URLSearchParams({ boardId, limit: "200" });
    if (cursor) params.set("cursor", cursor);

    const res = await fetch(
      `https://acme.probeya.com/api/v1/items?${params}`,
      { headers: { Authorization: "Bearer probeya_sk_live_abc123..." } }
    );
    const json = await res.json();

    items.push(...json.data);
    cursor = json.meta.cursor;
  } while (cursor);

  return items;
}

​
Best Practices

​
Errors

HTTP StatusError CodeCause
400BAD_REQUESTlimit outside the 1–200 range
400BAD_REQUESTInvalid or malformed cursor value
401UNAUTHORIZEDMissing or invalid Bearer token

Was this page helpful?

AuthenticationRate Limiting