Pagination

Canary returns opaque cursors that belong to one endpoint and one set of filters. Send the cursor back unchanged and keep every other query parameter stable throughout a traversal.

Choose the endpoint variant

Variant	Endpoints	Default	Maximum	Direction
ID cursor	Assets, locations, parts, meters, native work orders, identifiers	20	100	`asc` or `desc`
Reading cursor	Meter readings	20	100	`asc` or `desc`
Compatibility cursor	Work requests and request portals	100	200	Fixed by endpoint

Custom-field definition lists return a complete array and have no pagination parameters.

ID cursor

Canary-native resources use the last resource ID as the continuation point. Their response carries pagination under meta.pagination:

{
  "data": [{ "id": "01JAY7C1NQZ5H2R8M4K6T9V3BP" }],
  "meta": {
    "request_id": "req_01JAY8FVDM6CH4R3X9Q2T7K5NP",
    "api_version": "v1",
    "pagination": {
      "cursor": "01JAY7C1NQZ5H2R8M4K6T9V3BP",
      "has_more": true
    }
  }
}

# First page
curl --fail-with-body \
  "https://api.oncanary.com/v1/assets?status=online&direction=desc&limit=100" \
  --header "Authorization: Bearer $CANARY_API_KEY"

# Following page
curl --fail-with-body \
  "https://api.oncanary.com/v1/assets?status=online&direction=desc&limit=100&cursor=01JAY7C1NQZ5H2R8M4K6T9V3BP" \
  --header "Authorization: Bearer $CANARY_API_KEY"

Continue while has_more is true. Use the returned cursor for the next request.

Reading cursor

Meter readings can share the same timestamp, so their opaque cursor combines reading_at and the reading ID. Read the value from meta.pagination.cursor and return it unchanged.

curl --fail-with-body \
  "https://api.oncanary.com/v1/meters/METER_ID/readings?direction=asc&limit=100&cursor=RETURNED_CURSOR" \
  --header "Authorization: Bearer $CANARY_API_KEY"

Starting with direction=asc is useful for chronological ingestion. A cursor created for one direction cannot be reused with the other direction.

Compatibility cursor

Work requests and request portals expose an encoded offset cursor through compatibility response fields:

{
  "workRequests": [],
  "nextCursor": "d29yay1yZXF1ZXN0OjEwMA",
  "nextPageUrl": "https://api.oncanary.com/v1/workrequests?limit=100&cursor=d29yay1yZXF1ZXN0OjEwMA"
}

Use nextPageUrl directly or pass nextCursor with the same filters. A final page sets both fields to null. Offset cursors reflect the current collection. Concurrent inserts, deletions, or status changes can shift later pages, so recurring synchronizations should reconcile records by ID.

Traverse a native list

const apiKey = process.env.CANARY_API_KEY;

async function listAllAssets() {
  const assets = [];
  let cursor;

  do {
    const url = new URL('https://api.oncanary.com/v1/assets');
    url.searchParams.set('limit', '100');
    url.searchParams.set('direction', 'asc');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const body = await response.json();
    if (!response.ok) throw new Error(`${body.code}: ${body.detail}`);

    assets.push(...body.data);
    cursor = body.meta.pagination.has_more
      ? body.meta.pagination.cursor
      : undefined;
  } while (cursor);

  return assets;
}

Cursor rules

Treat every cursor as an opaque, short-lived token.
Keep filters, page size, direction, endpoint, and organization fixed.
Restart without a cursor after changing any of those values.
Deduplicate by resource ID in long-running or compatibility traversals.
Persist your own synchronization checkpoint after processing a complete page.

API essentials

Work management

Equipment

Inventory

Organization data

Pagination

Choose the endpoint variant

ID cursor

Reading cursor

Compatibility cursor

Traverse a native list

Cursor rules

​Pagination

​Choose the endpoint variant

​ID cursor

​Reading cursor

​Compatibility cursor

​Traverse a native list

​Cursor rules

Pagination

Choose the endpoint variant

ID cursor

Reading cursor

Compatibility cursor

Traverse a native list

Cursor rules