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:
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 fullnext 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
Sendgeneration 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. PassbaseURL, 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.