getLedgers
Read ledgers with their header and metadata XDR.
startLedger (or from a cursor), each with its hash, close time, header XDR and metadata XDR. Pass the returned cursor to read the next page.
The examples call Testnet with your key in LUMEUS_API_KEY; the SDK tabs use @stellar/stellar-sdk and the Python stellar-sdk (SDK setup and errors) (the curl example uses jq). On Mainnet, use https://rpc.lumeus.dev and a lum_live_ key.
Result
The fields ofresult (stellar-rpc 29). Fields marked “Present only when it applies” can be absent.
Parameters
Credits and limits
- Mainnet: 2 credits plus 1 credit per started 64 KiB of response, so a small answer costs 3 credits. A call that returns a JSON-RPC error costs nothing.
- Testnet: free. Each call counts toward your organization’s 10,000 Testnet requests a day; above that, calls get 429
rate_limiteduntil 00:00 UTC. - Mainnet pages are small because one Mainnet ledger with metadata is about 1 to 2.3 MB and a page must fit the 64 MiB response ceiling. A larger
limitanswers 400pagination limit must be 1 to 20. The example response shortens the XDR fields. - The plan RPC rate applies per call; each call in a batch counts as one.
Errors
Gateway errors are JSON-RPC errors with the machine code inerror.data and the request ID in error.request_id. Common ones: -32602 (invalid_request, HTTP 400) for invalid params, -32000 with unauthorized (401), rate_limited (429, wait Retry-After seconds) or unavailable (503). See errors.Authorizations
Send Authorization: Bearer <key>. Testnet: lum_test_…; Mainnet: lum_live_…. A key works only on its own network, so pick the server that matches it (the other network answers 401). Publishable lum_pub_… keys call read-only methods only, from an allowed browser origin. Dashboard sessions and webhook keys are not accepted.
Headers
Optional, and not used for deduplication: the response then carries X-Lumeus-Idempotency: ignored. To retry sendTransaction safely, resubmit the same signed envelope (the node answers DUPLICATE).
8 - 128"retry-0001-2026-10-22"
Body
Returns a page of ledgers with their header and metadata XDR, starting at startLedger or a cursor. 2 credits plus one per started 64 KiB of response. Named params only (positional arrays are rejected). A params member set to null (as Python stellar-sdk sends for unset options) is treated as omitted at any depth. startLedger 0 next to a cursor, endLedger 0 and pagination.limit 0 mean "not set", as on stellar-rpc.
Always 2.0.
2.0 Request ID, echoed in the response. Send one on every call: a call without an id is a notification, which runs but gets an empty 204 response. A string ID (at most 1024 bytes) also works and is echoed unchanged.
1
getLedgers - From startLedger
- From a cursor
Response
The getLedgers result. Check error before reading result.
- Result
- Error
A JSON-RPC 2.0 response: result on success, error otherwise. A JSON-RPC error can arrive with HTTP 200 (for example from the node, or for one child of a batch). Gateway errors carry the code string in error.data and the request ID in error.request_id; they echo your id when the body is a parseable single request and use a null id when it cannot be determined. Preserve integer IDs exactly; avoid unsafe JavaScript numeric IDs. The gateway never answers 502 or 504.
2.0 The id of your call, echoed unchanged (a string id comes back as a string). null when the gateway cannot read the id, for example for invalid JSON.
The getLedgers result, as returned by stellar-rpc 29.