Skip to main content
Every Activity collection returns pages with a fixed snapshot and a next link. This page explains the page fields and how to walk a range to its end without missing or repeating events. Set these once in your terminal. The sample values are real Testnet data, so the read examples return real results.

Page through a range

Follow _links.next until range_complete is true. This loop reads the last 200 ledgers of an account, oldest first:
Save the records and the next link together after each page, so a restart resumes where it stopped. The loop retries only rate_limited, busy, index_not_ready and unavailable, at most 5 times in a row, and stops when Retry-After is over 60 seconds (the daily Testnet request cap, which resets at 00:00 UTC). query_timeout is not retried on purpose: narrow the range instead (see snapshot and errors).

Page fields

paging_token on each record is the cursor of that record. Treat it as opaque: it is neither an event ID nor a page number.

Follow the returned URL

Use the full next URL as it is: it carries the cursor, order, range, generation and snapshot_ledger. Resolve it against the same Activity host and never send your key to another origin. range_complete is exact. A full final page can already be complete, so you need no extra request to confirm the end. A page can hold fewer records than limit, or none, while range_complete is false. There is no maximum range width, but each page scans the index for at most about 8 seconds and then returns what it found; next resumes after the last fully scanned ledger. A page also ends early when cold history is slow to read or its records reach 16 MiB; next then continues after the last record. A short or empty page is not the end of the range.

Checkpoints

scanned_through_ledger is present on every complete page, in both orders, and on ascending pages that the scan budget stopped early. Save it with your records as the ledger through which your copy is complete, even when no events matched. Do not use the largest event ledger you received. A since_ledger beyond the snapshot is not an error. The page is empty and complete, has no next, and reports scanned_through_ledger equal to read_view.snapshot_ledger. A sync loop can always save the checkpoint it gets back and ask again later.

Snapshot and errors

Send generation and snapshot_ledger together, or neither. The same rule applies to transaction-header requests. Idempotency-Key is optional on reads. If you send it, it must be 8 to 128 printable ASCII characters without spaces, or the request returns 400. On Free and paid plans it is checked and otherwise ignored; see idempotency. All codes are in errors.

JavaScript client

activity-client.mjs is a bounded async page iterator for production use. Pass baseURL, apiKey, initialPath and an idForURL callback that durably returns the same key for a URL. It stops when range_complete is true, retries 429, busy, index_not_ready, unavailable and other 5xx up to 3 times while honoring Retry-After (a Retry-After over 60 seconds throws instead of sleeping), and throws an ActivityError (with code, requestID and retryAfter) on query_timeout and every other error, so you can narrow the range. It rejects cross-origin links, changed snapshots and cycles. It reads at most 10 pages by default; save your next link to resume.