Query audit logs
Returns audit trail of all authenticated operations. Essential for compliance (SOC2, GDPR, etc.).
RETENTION: - Recommended: 90 days hot, 1 year cold storage - Critical for security incident investigation
FILTERING: - By tenant, key, time range, operation, status - Supports complex queries for forensics
Authorizations
Administrative API key with full system access. Also accepted as an alternative to ApiKeyAuth on an explicit per-operation allowlist — the authoritative list is the union of operations whose security: block declares AdminKeyAuth (consult per-operation security blocks rather than this prose, which has historically drifted as the dual-auth surface expanded). When using AdminKeyAuth on list or fund endpoints, a tenant scoping parameter (typically tenant or tenant_id) is required for scoping (400 if missing) — the per-operation description specifies which. Lookup-style endpoints that uniquely identify a resource by non-tenant key (e.g. GET /v1/admin/budgets/lookup, where the (scope, unit) pair is unique) do NOT require a tenant parameter. Allowlisting is per-operation (exact method:path matching — no prefix matching, no wildcards) so new endpoints do not accidentally inherit admin-accessible status.
Parameters
Query Parameters
Filter by exact tenant id. Accepts the two documented sentinels in addition to real tenant ids: ?tenant_id=__admin__ surfaces admin-plane activity; ?tenant_id=__unauth__ surfaces the failed-pre-auth stream. See AuditLogEntry.tenant_id for full sentinel semantics.
Filter by operation ID. Exact-or-IN-list. Formal wire contract is the explode=false comma-separated form — a single scalar ?operation=createBudget or a comma- separated list ?operation=createBudget,updateBudget. Servers MAY additionally accept the repeated form ?operation=createBudget&operation=updateBudget as an implementation convenience; clients MUST NOT rely on it for portability. IN-list members are OR-composed; the predicate AND-composes with other filters. maxItems 25. Additive shape promotion — older clients sending a single scalar continue to work byte-identically on servers implementing this revision.
25Filter by exact HTTP status. MUST NOT combine with status_min or status_max (server MUST reject the combination with HTTP 400 INVALID_REQUEST).
Filter by resource type (e.g., budget, tenant, api_key, policy, webhook, config). Exact-or-IN-list. Formal wire contract is the explode=false comma-separated form (single scalar or ?resource_type=budget,tenant). Servers MAY additionally accept the repeated form as an implementation convenience; clients MUST NOT rely on it. maxItems 25. Additive shape promotion — older clients sending a single scalar continue to work byte-identically.
25Filter by resource ID (e.g., ledger ID, key ID, subscription ID)
Filter by audit entry error_code. Exact-or-IN-list. Formal wire contract is the explode=false comma- separated form. Servers MAY additionally accept the repeated form as an implementation convenience; clients MUST NOT rely on it. Case-sensitive. IN-list members are OR-composed; the predicate AND-composes with other filters. maxItems 25.
NULL entry error_code (success entries) MUST NOT match — auditors asking "show me code X" never want success rows.
Forward-compat: values are NOT validated against the ErrorCode enum. Unknown codes match nothing at the filter layer (a newer client sending a newly-added enum value MUST NOT cause a 400 against an older server).
Additive parameter — servers that don't recognize it MUST ignore without error.
25NOT-IN-list filter on audit entry error_code. Removes matching rows from the result set.
NULL entry error_code MUST always pass — hiding noisy codes (e.g., INTERNAL_ERROR) MUST NOT silently hide successful (null-error_code) entries.
MAY combine with error_code (AND-composed: "narrow to set A, minus subset B"). Case-sensitive. maxItems 25.
Additive parameter — servers that don't recognize it MUST ignore without error.
25Inclusive lower bound on audit entry status. MUST be in [100, 599]. MUST NOT combine with exact status (server MUST reject the combination with HTTP 400 INVALID_REQUEST). When both status_min and status_max are present, server MUST reject status_min > status_max with HTTP 400.
NULL entry status MUST NOT silently pass the range predicate; entries with absent status are treated as out-of-range for any numeric bound.
Additive parameter — servers that don't recognize it MUST ignore without error.
100599Inclusive upper bound on audit entry status. MUST be in [100, 599]. MUST NOT combine with exact status. NULL entry status does not satisfy the bound (see status_min for the identical NULL rule).
Additive parameter — servers that don't recognize it MUST ignore without error.
100599"date-time""date-time"Free-text case-insensitive substring match. Matches across: resource_id, log_id, error_code, operation. Combined with other filter params using AND semantics. Additive parameter — servers that don't recognize it MUST ignore without error (additive-parameter guarantee). Empty string MUST be treated as absent. Max length 128 characters; longer values MUST be rejected with HTTP 400.
128Filter by exact trace_id. 32 lowercase hex characters (W3C Trace Context trace-id). Narrows the audit log to entries belonging to a single logical operation (may span multiple HTTP requests). When combined with other filters, AND-composed. Additive parameter — servers that don't recognize it MUST ignore without error (additive-parameter guarantee). See CORRELATION AND TRACING in cycles-protocol-v0.yaml.
"^[0-9a-f]{32}$"Filter by exact request_id. Narrows the audit log to the entry produced by a single HTTP request. When combined with other filters, AND-composed. Typically yields 0 or 1 row (one audit entry per authenticated request). Additive parameter — servers that don't recognize it MUST ignore without error (additive-parameter guarantee).
Sort key. When provided, results are returned in the requested order and the returned cursor encodes the sort key so "Load more" continues in sort order. When omitted, servers use their existing default ordering. Servers that don't recognize the parameter MUST ignore it without error (additive-parameter guarantee).
"timestamp""operation""resource_type""tenant_id""key_id""status""timestamp"Sort direction. Default descending.
"asc""desc""desc"50Responses
Audit log entries