---
title: "List audit entries"
method: GET
path: "/v3/_/audit-entries"
tags: ["Audit"]
---

# List audit entries

`GET /v3/_/audit-entries`

## Request

- Base URL: `http://localhost:9000`
- URL: `http://localhost:9000/v3/_/audit-entries`
- Auth: one of:
  - HTTP bearer
  - none

Lists audit trail entries (one per proposal, success or failure) across
the whole bucket, paged by audit sequence (ascending unless
`reverse=true`). Audit reads are
not ledger-scoped in the path — a single proposal can touch several
ledgers — so ledger scope, outcome and other dimensions are expressed
through the `filter` query parameter.

This endpoint always performs a live read and does not expose pinned
checkpoint reads. Filters containing indexed audit conditions wait for
the audit projection to certify the request's fixed main-store horizon;
matching entries are loaded from that same main snapshot. Unfiltered
reads and sequence-only bounds scan the audit zone directly without
waiting for the audit projection.

Requires `ledger:ReadAudit` 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": <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
- `filter` string

## Headers

- `X-Consistency` 'linearizable' | 'stale'

## Response `200`

List of audit entries

- object
  - `data` AuditEntry[], required
    - `sequence` integer: Global audit sequence number
    - `timestamp` string, date-time: Apply timestamp (RFC3339)
    - `proposalId` integer: Identifier of the proposal that produced this entry
    - `success` AuditSuccess: The inclusive log sequence range created by a successful proposal.
      - `minLogSequence` integer
      - `maxLogSequence` integer
    - `failure` AuditFailure: Stable reason, subcode, and facts for a failed proposal. Presentation text is rendered when read and is not stored in the audit chain.
      - `reason` string: Typed error reason identifier (e.g. ERROR_REASON_INSUFFICIENT_FUNDS)
      - `code` string: Stable failure subcode
      - `facts` object: Validated facts used to render the failure
    - `orderCount` integer: Number of orders in the proposal
    - `items` AuditItem[]: Per-order detail lines. Populated by the single-entry lookup; empty on list.
      - `orderIndex` integer: Zero-based position of this order within the proposal
      - `serializedOrder` string: Hex-encoded deterministic serialized bytes of the order at apply time
      - `logSequence` integer: Sequence of the log produced by this order (0 for idempotent replay or failed proposals)
    - `ledgers` string[]: Distinct ledger names targeted by the proposal's orders
    - `hash` string: Hex-encoded batch integrity hash chaining audit entries
    - `hashVersion` integer: Hash algorithm version
    - `callerSnapshot` object: Admission-time auth snapshot (protobuf JSON); absent when auth is disabled or for system proposals
    - `idempotency` object: Batch identity / idempotency information (protobuf JSON)
    - `signature` object: Client signature over the ApplyBatch (protobuf JSON); absent for unsigned batches
  - `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)
- `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 `listAuditEntries` removed and replaced with `v3ListAuditEntries`
- **2026-10-14** `5e39ed0a6af9`: 2 warning, 2 info
  - removed the optional property `data/items/failure/context` from the response with the `200` status
  - removed the optional property `data/items/failure/message` from the response with the `200` status
  - added the optional property `data/items/failure/code` to the response with the `200` status
  - added the optional property `data/items/failure/facts` to the response with the `200` status
- **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 optional property `next` to the response with the `200` status
  - …3 more

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