Sign in
audit

One bounded page of the organization's audit trail.

Changed on

Reads one bounded page of the append-only trail in stable commit-sequence order, oldest first. Filtering by principal, operation, outcome and resource identifiers is applied to the page after it is read, so a page SCANS limit rows and RETURNS the subset that matched: next_after_seq is the seq of the last row scanned (the resume cursor), and exhausted is true only when the scan reached the end of the trail. A sparse filter therefore returns few or zero items with exhausted false — that means keep paging, not "no such events".

Reading the trail is itself audited, unconditionally: each page commits one audit.query event recording the normalized filter and the count returned, durably, in the same transaction as the read. No value material is ever in the trail, so none can be in this response.

Consistency limit of interactive paging: pages are ordered by the allocation seq. A transaction that commits out of allocation order can land below a cursor that has already passed it, so that event can be absent from the remainder of one paging session. It is durable and a fresh query recovers it. Exports do not have this limit: they page in commit order behind the writer barrier and are gap-free.

get/api/v1/orgs/{org}/audit

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/orgs/{org}/audit
  • Auth: HTTP bearer

Query parameters

fromstring date-time

Inclusive lower time bound (recorded-at). Absent means the epoch.

tostring date-time

Inclusive upper time bound (recorded-at). Absent means unbounded.

after_seqinteger

Resume cursor: return events whose seq is strictly greater. Pass the previous page's next_after_seq to page forward.

to_seqinteger

The session ceiling. Absent on the first page (the server pins it to the trail's current head and returns it as upper_seq); pass that value back on every later page so paging terminates and never chases the audit.query events the reads themselves append.

limitinteger

Maximum rows SCANNED for this page (clamped to 1000). Matched rows may be fewer when a filter is set.

actorstring

Match only events whose acting principal has this id (exact).

actor_namestring

Match only events whose acting principal's display name (or username) matches this pattern. Supports * wildcards (e.g. alice*, *bot). Names are resolved only for principals that already appear in the trail you are authorized to read; this filter narrows that view and performs no directory lookup, so it discloses nothing you cannot already see.

operationstring

Match only events of this type (the operation), e.g. value.set. Supports * wildcards (e.g. value.*). An unknown or unmatched pattern is not an error; it simply matches nothing.

outcome'intent' | 'success' | 'denied' | 'failure' | 'unknown' | 'disconnected'

Match only events with this outcome. To match several outcomes, use the repeatable outcomes parameter; both may be given and are unioned.

outcomesstring[]

Match events with any of these outcomes (set membership). Repeat the parameter to select several, e.g. outcomes=denied&outcomes=failure. Unioned with the singular outcome when both are present.

object_typestring

Match only events acting on this object type. Supports * wildcards (e.g. secret*).

object_idstring

Match only events acting on this object id. Supports * wildcards.

correlation_idstring

Match only events sharing this correlation id — the link between an act's INTENT and OUTCOME events.

Response

One page of trail events.

countinteger required

Number of matched events returned (may be fewer than the rows scanned).

next_after_seqinteger required

The seq of the last row SCANNED. Pass it as after_seq to resume; it advances over scanned rows, not just matched ones, so a filtered page never re-reads or skips.

upper_seqinteger required

The session ceiling the server pinned for this paging run (the trail's head when the first page was read). Pass it back as to_seq on every later page; it never changes across the run.

exhaustedboolean required

True when this page reached the end of the trail (fewer rows scanned than the limit). While false, more pages remain even if items is empty for a sparse filter.

Changes

  • f24ca8785e72Revision changes
    • info

      added the non-success response with the status

  • 54b2780eec85Revision changes
    • info

      added the optional property / to 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

    • info

      added the optional property / to 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