Audit query and export API

Audit query and export API

Read accountable change records and export retained intervals with explicit cursors.

Audit endpoints read administrative action records. They do not substitute for operation outcomes or component journals.

Query

GET/organizations/{organization_id}/audit-events
Scope
audit:read
Auth
Bearer API key

Returns audit events within the caller's permitted scope.

Requires audit:read. Filters are actor_id, action, project_id, resource_id, request_id, start, and end, with standard cursor pagination. Start is inclusive and end exclusive. Records outside the caller's permitted audit scope are excluded.

A query response includes accountable actor and operation references:

JSON
{
  "data": [
    {
      "id": "aud_protection01",
      "occurred_at": "2026-05-06T12:03:00Z",
      "actor": { "type": "service_account", "id": "svc_deployer" },
      "action": "droplet.update",
      "project_id": "prj_payments",
      "resource_id": "drp_web01",
      "request_id": "req_change01",
      "operation_id": "op_change01",
      "changes": { "deletion_protection": { "before": false, "after": true } }
    }
  ],
  "pagination": { "next_cursor": null }
}

Secret values and bearer tokens are excluded from ordinary change payloads. Names and labels remain user-supplied audit content and must not be used to store secrets.

Correlate execution

An accepted action can later fail. Follow operation_id with operations:read to determine its execution result. An event with no operation reference can represent a synchronous metadata change or a rejected request.

Historical resource IDs remain searchable after deletion. Their former display names are recorded at event time and need not match a later reused name.

Export

POST/organizations/{organization_id}/audit-exports
Scope
audit:export
Auth
Bearer API key

Creates a bounded audit export at an approved destination.

Send bounded start, end, filters, and an approved destination_id. The caller must also be allowed to read the selected audit scope. Returns 202 with export ID and operation.

An invalid interval returns 422 invalid_time_range. A forbidden destination returns 422 policy_violation. The completed artifact identifies filters, generation time, and event IDs; the destination's retention applies independently.

Cursor recovery

Audit streaming uses opaque delivery cursors distinct from query timestamps. A retained cursor can be replayed through the configured sink workflow. An expired cursor returns 410 cursor_expired; resuming at the latest cursor does not recover the missing interval.

Exported copies can contain repeated event IDs after a replay. Consumers should deduplicate rather than generating a new external change record per delivery. See audit streaming, audit retention, and data residency.

Integrity manifests

Completed signed exports include a manifest reference, artifact digests, declared record range, chunk links when applicable, and signing-key ID. Download and verification remain subject to export access and artifact expiry.

An integrity result establishes correspondence with that declared signed set; it cannot prove completeness outside the selected scope. See audit integrity for trusted keys, rotation, and gap detection.