Pagination and snapshots¶
Use pagination: "snapshot" for a complete bounded export on a release 0.2 server. The default offset mode remains a live view for compatibility and can shift while records are inserted, edited or deleted.
Snapshot workflow¶
- Call
list_drivesorlist_work_sessionswithfrom,to,pagination: "snapshot"and a chosenlimit. Omitcursorandoffset. - Process the returned rows. Preserve their source identity in your application.
- If
next_cursoris notnull, repeat the same tool, dates, driver filter, limit and pagination mode, addingcursor: next_cursor. - Continue until
next_cursorisnull, including after an empty page.
{
"from": "2026-11-20",
"to": "2026-11-20",
"pagination": "snapshot",
"limit": 100,
"cursor": "<next_cursor from the previous response>"
}
Treat the cursor as opaque. It is bound to the authenticated user, fleet, resource type, query and page size. It does not replace authentication, and cannot grant access after revocation or lost eligibility.
Limits¶
| Limit | Release 0.2 behavior |
|---|---|
| Page size | 1–100 records; default 25 |
| Date range | At most 366 inclusive dates, YYYY-MM-DD |
| Snapshot lifetime | 15 minutes from creation |
| Active snapshots | At most 3 per fleet, shared between both list tools |
| Snapshot record count | At most 10,000 |
| Snapshot encoded JSON before encryption | At most 4 MiB, including the authorization envelope |
Oversized snapshots are rejected; they are not silently cut off. Split the date range into smaller queries. Avoid starting multiple snapshots unnecessarily.
What remains stable¶
The source values and ordering are captured when the snapshot is created. Later inserts do not enter that snapshot; ordinary edits do not move records between its pages.
Current access and row visibility still take precedence. A record that is deleted, moved to another fleet, or reclassified as private/unknown is withheld when a page is read. This can produce a short or empty page with a non-null continuation cursor. Do not infer a reliable deletion event from a missing row.
A new snapshot can contain newer values for the same record. Snapshot cursors are temporary pagination tokens, not long-term synchronization checkpoints.
Offset mode¶
Existing clients can use limit, offset and next_offset. The maximum accepted offset is 10,000. Do not combine an offset cursor with snapshot mode, or pass a snapshot cursor with offset mode.
Offset pagination does not freeze the dataset. For financial exports or reconciliation, use snapshot mode and the data lifecycle rules.