---
title: "List logs for a ledger"
method: GET
path: "/v3/{ledgerName}/logs"
tags: ["Logs"]
---

# List logs for a ledger

`GET /v3/{ledgerName}/logs`

## Request

- Base URL: `http://localhost:9000`
- URL: `http://localhost:9000/v3/{ledgerName}/logs`
- Auth: one of:
  - HTTP bearer
  - none

Lists log entries for a specific ledger, paged by ledger-local log ID
(ascending unless `reverse=true`).
Requires the builtin `LOG` index to be enabled on the ledger via `CreateIndex`.
Requires `ledger:read` scope.

## Path parameters

- `ledgerName` string, required

## 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": <string>, "back": <bool>}`. 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
- `startDate` string, date-time
- `endDate` string, date-time
- `filter` string

## Headers

- `X-Consistency` 'linearizable' | 'stale'
- `Formance-Bigint-As-String` string

## Response `200`

Logs retrieved successfully

- object
  - `data` SystemLog[], required
    - `sequence` integer
    - `payload` object: Named system payload variants are preserved as supplied, including nested fields and future sibling variants. Only apply is typed here; other variants remain open-ended (EN-2781).
      - `apply` object
        - `ledgerName` string
        - `log` LedgerLog: Ledger-local log. The type selects the direct object in data, following the v2 type/data structure; data has no variant-name wrapper. New v3 operations have distinct type values. Metadata remains typed, volumes retain colors, and reversals contain the original transaction ID and the reversing transaction rather than the full original transaction. This JSON projection is not an audit replay or backup format.
          - `type` 'NEW_TRANSACTION' | 'REVERTED_TRANSACTION' | 'SET_METADATA' | 'DELETE_METADATA' | 'SET_METADATA_FIELD_TYPE' | 'REMOVED_METADATA_FIELD_TYPE' | 'ORDER_SKIPPED' | 'FILL_GAP' | 'CREATE_INDEX' | 'DROP_INDEX' | 'ADDED_ACCOUNT_TYPE' | 'REMOVED_ACCOUNT_TYPE' | 'UPDATED_DEFAULT_ENFORCEMENT_MODE', required
          - `data` object, required: Direct operation payload selected by type. NEW_TRANSACTION contains transaction and optional accountMetadata. REVERTED_TRANSACTION contains revertedTransactionId and revertTransaction. SET_METADATA and DELETE_METADATA contain targetType (ACCOUNT or TRANSACTION) and targetId: an account-address string or an unsigned 64-bit transaction integer, including zero. SET_METADATA also contains metadata; DELETE_METADATA contains key. ORDER_SKIPPED contains reason and optional context. Other types carry the fields of their corresponding operation directly. FILL_GAP contains originalId, a uint64 encoded as a decimal JSON string by protobuf JSON. Transaction IDs, revertedTransactionId and transaction targetId are JSON numbers; consumers must preserve full integer precision. Metadata integers are JSON numbers and null-valued keys are preserved.
          - `date` string, date-time
          - `id` integer: Ledger-local log ID; omitted when zero.
    - `responseSignature` object
  - `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": <string>, "back": <bool>}`. 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": <string>, "back": <bool>}`. 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)
- `404`: Not found
- `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 `listLedgerLogs` removed and replaced with `v3ListLedgerLogs`
- **2026-10-09** `0ed18e459f51`: 1 info
  - added the new optional `header` request parameter `Formance-Bigint-As-String`
- **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`: 1 breaking, 1 warning, 5 info
  - for the `query` request parameter `pageSize`, default value was changed from `0` to `100`
  - deleted the `query` request parameter `after`
  - added the new optional `query` request parameter `cursor`
  - added the new optional `query` request parameter `reverse`
  - …3 more

[Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/:ledgerName/logs/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)