--- title: "List all ledgers" method: GET path: "/v3/" tags: ["Ledgers"] --- # List all ledgers `GET /v3/` ## Request - Base URL: `http://localhost:9000` - URL: `http://localhost:9000/v3/` - Auth: one of: - HTTP bearer - none Lists the ledgers in the cluster, paged by name (ascending unless `reverse=true`). Requires `ledger:read` scope. ## Query parameters - `pageSize` integer - `cursor` string: Page token of a paged list. Clients normally pass back the `next` or `previous` value of a previous response verbatim; building one by hand is supported. A token is base64url (unpadded, RFC 4648 §5) of the JSON object `{"key": , "back": }`. Both fields are omitted when empty, and unknown fields are rejected. `key` is a position in the endpoint's textual form: - transactions: decimal transaction id - logs: decimal ledger-local log id - audit entries: decimal audit sequence - accounts: address - ledgers and numscripts: name - signing keys: key id - prepared queries: decimal id for TRANSACTIONS and LOGS targets, address for ACCOUNTS - index inspection: base64url of the encoded metadata value Both directions exclude the key and return rows in the requested order (`reverse` included): - `{"key": K}` serves the rows strictly after K; - `{"key": K, "back": true}` serves the page that ends strictly before K; - `{"back": true}` serves the last page; - an absent or empty token, or `e30` (`{}`), serves the first page. On a forward page, `next` is set when a further row follows the page, and `previous` whenever the request carried a key. On a back page, `previous` is set when a further row precedes the page, and `next` whenever the request carried a key. A first page therefore has no `previous`, and the last page requested with `{"back": true}` has no `next`. A malformed token, or a key that is not a valid position for the endpoint, is rejected with 400 `INVALID_REQUEST`. - `reverse` boolean ## Headers - `X-Consistency` 'linearizable' | 'stale' ## Response `200` List of ledgers retrieved successfully - ListAllLedgersResponse - `data` LedgerInfo[], required: One page of ledgers, in the requested name order - `name` string, required: Name of the ledger - `createdAt` string, date-time - `deletedAt` string, date-time: Soft deletion timestamp; omitted for active ledgers - `metadata` object: Enriched typed ledger metadata - `metadataSchema` LedgerMetadataSchema - `accountFields` object - `transactionFields` object - `ledgerFields` object - `mode` 'NORMAL' | 'MIRROR', required: Ledger mode, including the default NORMAL value - `mirrorSource` union: Detached credential-safe mirror configuration returned by ledger reads - object - `ledgerName` string, required - `batchSize` integer - `rewriteRules` MirrorRewriteRuleRead[] - `createdTransaction` CreatedTransactionRuleRead: Rule scoped to MirrorCreatedTransaction. Inside `match`, `log` is the created-transaction proto directly (e.g. `log.metadata["k"]`). - `match` string - `actions` CreatedTransactionActionRead[] - … - `revertedTransaction` RevertedTransactionRuleRead - `match` string - `actions` RevertedTransactionActionRead[] - … - `savedMetadata` SavedMetadataRuleRead - `match` string - `actions` SavedMetadataActionRead[] - … - `deletedMetadata` DeletedMetadataRuleRead - `match` string - `actions` DeletedMetadataActionRead[] - … - `anyVariant` AnyVariantRuleRead: Rule scoped to every variant. `log` is the full MirrorLogEntry — use `has(log.)` guards to read variant-specific fields. - `match` string - `actions` AnyVariantActionRead[] - … - `stop` boolean - `http` HttpMirrorSourceRead, required - `baseUrl` string: Source URL with userinfo (including passwordless tokens) and query credentials masked - `oauth2ClientCredentials` MirrorOAuthRead - `clientId` string - `clientSecret` '[redacted]': Presence marker only; reusable secret material is never returned - `tokenEndpoint` string: OAuth endpoint URL with userinfo (including passwordless tokens) and query credentials masked - `scopes` string[] - `postgres` PostgresMirrorSourceRead - `dsn` string: Connection string with password material masked; malformed values are fully redacted - `awsIamAuth` MirrorAwsIamAuthRead - `region` string - `assumeRoleArn` string - object - `ledgerName` string, required - `batchSize` integer - `rewriteRules` MirrorRewriteRuleRead[] - `createdTransaction` CreatedTransactionRuleRead: Rule scoped to MirrorCreatedTransaction. Inside `match`, `log` is the created-transaction proto directly (e.g. `log.metadata["k"]`). - `match` string - `actions` CreatedTransactionActionRead[] - … - `revertedTransaction` RevertedTransactionRuleRead - `match` string - `actions` RevertedTransactionActionRead[] - … - `savedMetadata` SavedMetadataRuleRead - `match` string - `actions` SavedMetadataActionRead[] - … - `deletedMetadata` DeletedMetadataRuleRead - `match` string - `actions` DeletedMetadataActionRead[] - … - `anyVariant` AnyVariantRuleRead: Rule scoped to every variant. `log` is the full MirrorLogEntry — use `has(log.)` guards to read variant-specific fields. - `match` string - `actions` AnyVariantActionRead[] - … - `stop` boolean - `http` HttpMirrorSourceRead - `baseUrl` string: Source URL with userinfo (including passwordless tokens) and query credentials masked - `oauth2ClientCredentials` MirrorOAuthRead - `clientId` string - `clientSecret` '[redacted]': Presence marker only; reusable secret material is never returned - `tokenEndpoint` string: OAuth endpoint URL with userinfo (including passwordless tokens) and query credentials masked - `scopes` string[] - `postgres` PostgresMirrorSourceRead, required - `dsn` string: Connection string with password material masked; malformed values are fully redacted - `awsIamAuth` MirrorAwsIamAuthRead - `region` string - `assumeRoleArn` string - `mirrorSyncProgress` MirrorSyncProgress: Sync progress for MIRROR ledgers (populated at read time) - `state` 'SYNCING' | 'FOLLOWING', required: Current sync state (SYNCING = catching up, FOLLOWING = up to date) - `cursor` string, bigint, required: Last ingested v2 log ID - `sourceLogCount` string, bigint, required: Latest known log ID in the v2 source - `remainingLogs` string, bigint, required: Number of remaining logs to sync (sourceLogCount - cursor) - `error` MirrorSyncError: Most recent mirror sync error (null if healthy) - `message` string: Error message - `occurredAt` string, date-time: When the error occurred - `accountTypes` object - `defaultEnforcementMode` 'STRICT' | 'AUDIT', required: Default enforcement for unmatched accounts; defaults to STRICT - `next` string: Page token of a paged list. Clients normally pass back the `next` or `previous` value of a previous response verbatim; building one by hand is supported. A token is base64url (unpadded, RFC 4648 §5) of the JSON object `{"key": , "back": }`. Both fields are omitted when empty, and unknown fields are rejected. `key` is a position in the endpoint's textual form: - transactions: decimal transaction id - logs: decimal ledger-local log id - audit entries: decimal audit sequence - accounts: address - ledgers and numscripts: name - signing keys: key id - prepared queries: decimal id for TRANSACTIONS and LOGS targets, address for ACCOUNTS - index inspection: base64url of the encoded metadata value Both directions exclude the key and return rows in the requested order (`reverse` included): - `{"key": K}` serves the rows strictly after K; - `{"key": K, "back": true}` serves the page that ends strictly before K; - `{"back": true}` serves the last page; - an absent or empty token, or `e30` (`{}`), serves the first page. On a forward page, `next` is set when a further row follows the page, and `previous` whenever the request carried a key. On a back page, `previous` is set when a further row precedes the page, and `next` whenever the request carried a key. A first page therefore has no `previous`, and the last page requested with `{"back": true}` has no `next`. A malformed token, or a key that is not a valid position for the endpoint, is rejected with 400 `INVALID_REQUEST`. - `previous` string: Page token of a paged list. Clients normally pass back the `next` or `previous` value of a previous response verbatim; building one by hand is supported. A token is base64url (unpadded, RFC 4648 §5) of the JSON object `{"key": , "back": }`. Both fields are omitted when empty, and unknown fields are rejected. `key` is a position in the endpoint's textual form: - transactions: decimal transaction id - logs: decimal ledger-local log id - audit entries: decimal audit sequence - accounts: address - ledgers and numscripts: name - signing keys: key id - prepared queries: decimal id for TRANSACTIONS and LOGS targets, address for ACCOUNTS - index inspection: base64url of the encoded metadata value Both directions exclude the key and return rows in the requested order (`reverse` included): - `{"key": K}` serves the rows strictly after K; - `{"key": K, "back": true}` serves the page that ends strictly before K; - `{"back": true}` serves the last page; - an absent or empty token, or `e30` (`{}`), serves the first page. On a forward page, `next` is set when a further row follows the page, and `previous` whenever the request carried a key. On a back page, `previous` is set when a further row precedes the page, and `next` whenever the request carried a key. A first page therefore has no `previous`, and the last page requested with `{"back": true}` has no `next`. A malformed token, or a key that is not a valid position for the endpoint, is rejected with 400 `INVALID_REQUEST`. - `hasMore` boolean, required: True when a following page exists; set iff `next` is. ## Other responses - `400`: Bad request - `401`: Authentication required (missing or invalid JWT token) - `403`: Insufficient permissions (missing required scope) - `405`: Method not allowed - `500`: Internal server error - `503`: Service unavailable — the server cannot serve the request right now but an immediate retry can succeed. The `errorCode` field discriminates the cause: `NO_LEADER` (no elected Raft leader), `CACHE_HORIZON_EXCEEDED` (admission snapshot too old, retry against a fresh one), `UNAVAILABLE` (an internal forwarded stream was torn down mid-transfer), or the reason of any domain error of the unavailable kind (e.g. `INDEX_BUILDING`). ## Changes - **2026-11-03** `f5e817eca038`: 1 info - api operation id `listAllLedgers` removed and replaced with `v3ListAllLedgers` - **2026-10-09** `45c54ddbb457`: 7 warning, 9 info - removed the optional property `data/items/account_types` from the response with the `200` status - removed the optional property `data/items/created_at` from the response with the `200` status - removed the optional property `data/items/default_enforcement_mode` from the response with the `200` status - removed the optional property `data/items/deleted_at` from the response with the `200` status - …12 more - **2026-10-08** `3da23d327316`: 2 info - added the media type `text/plain` for the response with the status `401` - added the media type `text/plain` for the response with the status `403` - **2026-10-08** `b3ee1959d86a`: 1 info - added the new optional `header` request parameter `X-Consistency` - **2026-10-08** `21be46727a2f`: 6 info - added the new optional `query` request parameter `cursor` - added the new optional `query` request parameter `pageSize` - added the new optional `query` request parameter `reverse` - added the optional property `next` to the response with the `200` status - …2 more [Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/get.md) --- [API](https://skmtc.dev/formancehq/apis/ledger-api.md) - [All operations](https://skmtc.dev/formancehq/apis/ledger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/formancehq/apis/ledger-api/revisions/f5e817eca038?raw)