FOformancehq
Audit

List audit entries

Changed on

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.

get/v3/_/audit-entries

Request

  • Base URL
    http://localhost:9000
  • URL
    http://localhost:9000/v3/_/audit-entries
  • Auth
    • HTTP bearer
    • or none

Query parameters

pageSizeinteger

Maximum number of items per page. 0 or absent means 100; values above 1000 are clamped to 1000.

cursorstring

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.

Page token from a previous response's next or previous field (see the PageToken schema). Omit for the first page. Pass the same reverse and filter on every page of a walk.

reverseboolean

Iterate newest-first (descending sequence) when true

filterstring

A filter, decoded by the same shared dual-format decoder every list endpoint uses (see the ListFilter parameter), restricted to bare audit fields (outcome, ledger, seq, proposal_id, timestamp, log_seq, caller_subject, order_type, idempotency_key). These are written without any prefix and are resolved against the audit query target (EN-1549 — this replaced the old audit[...] namespaced syntax; it is a breaking change with no backward compatibility):

  • outcome == failure
  • ledger == main
  • order_type in (create_transaction, revert_transaction)
  • seq between 1000 and 2000
  • timestamp >= "2023-11-14T22:13:20Z"
  • idempotency_key == "retry-123"
  • idempotency_key ^= "import-2026-" Supported fields: seq, proposal_id, log_seq (numeric); timestamp (RFC3339 or unix microseconds); outcome (success|failure), ledger, caller_subject, order_type, idempotency_key (string; idempotency_key also supports prefix matching with ^=; a reused key returns every historical audit entry; bare alphanumeric values are accepted unquoted, while values containing -, :, spaces, or other non-identifier characters must be single- or double-quoted; keys containing both " and ' cannot be expressed in the textual DSL: use the structured form for exact and in lookups ({"$match":{"idempotency_key":"…"}}, an $or of such leaves) and the gRPC API directly (AuditCondition.string_prefix) for prefix lookups). Bare audit fields are resolved against the audit query target: timestamp and ledger collide with the transaction timestamp field and the top-level ledger condition, so on the audit target they resolve to the audit condition (and only there — hence audit fields are valid on this endpoint only). The structured JSON form uses the same bare field names, resolved against the audit target the same way: {"$match":{"outcome":"failure"}}, {"$gte":{"seq":1000}}, {"$match":{"idempotency_key":"retry-123"}}. Parameters ({"$param": …}) are rejected on audit fields, and the idempotency_key ^= prefix match has no structured form (the JSON DSL has no prefix operator).

Headers

X-Consistency'linearizable' | 'stale'

Read consistency. linearizable (the default) runs a Raft ReadIndex barrier and waits for the receiving node to apply up to it. stale serves the read from the receiving node's own store, with no barrier and no forwarding to the leader, so the answer may lag the leader. Matching ignores case and surrounding whitespace. An unknown value, or a repeated or comma-joined header, returns 400 INVALID_REQUEST on every /v3 route, writes included; a valid value has no effect on writes. The gRPC equivalent is the x-consistency request metadata.

Response

List of audit entries

nextstring

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.

previousstring

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.

hasMoreboolean required

True when a following page exists; set iff next is.

Changes

  • f5e817eca038Revision changes
    • info

      api operation id listAuditEntries removed and replaced with v3ListAuditEntries

  • 5e39ed0a6af9Revision changes
    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status