Audit events

Audit events are the durable evidence trail for every governed action in a workspace. Each event records who acted, on what, under which scope, and with what result.

Refer to Audit events concept for how the trail is shaped.

Overview

Audit v1 is the public envelope and service version; the current event registry is the schema-v4 catalog. Stream Live Events shows the same record in real time. Export delivers retained history downstream. Continuous SIEM streaming is a separate forward-only path on Export data.

The typical workflow is:

1. Browse the event catalog when you need field names and filterable payload keys.
2. Query events with class, actor, resource, correlation, or payload filters.
3. Get an event by ID when you need the full envelope.
4. List or get an activity chain, or emit an activity_id for a run.

Requirements

Before you begin:

• Authenticate to Dome and select a workspace
• Have audit events in the workspace, or emit activity so chains appear

Permissions

Audit reads require platform permissions. People and scoped API keys query the trail. Agent credentials are not the usual path for investigation.

All workspace roles can query events, get an event by ID, and list or get activity chains with audit.view. Org owner and admin can also use org-scoped audit.view to query across the organization. Live streaming on Stream Live Events uses the same permission. Batch and scheduled delivery live under Export Data.

Browse the event catalog

List every audit event type Dome emits, then show field detail for one type. The same catalog powers the dashboard Event Catalog tab.

dome audit catalog list
dome audit catalog show tool.call

{ "event_type": "tool.call" }

Query events

Query recent audit events. The default page returns the latest 50. Combine class, result, actor, resource, correlation, payload, and time filters to narrow the trail.

Common flags: --limit, --types, --classes, --results, --agent-id, --since, --until, and repeatable --payload-filter. Full flags: refer to the CLI, MCP, and API references in the callouts below.

dome audit query --limit 10

{ "limit": 10 }

GET /v1/audit/events?page_size=10

{
  "event_types": ["tool.call"],
  "stages": ["STAGE_ATTEMPTED", "STAGE_COMPLETED"],
  "event_classes": ["EVENT_CLASS_GOVERNING"],
  "results": ["RESULT_DENIED"],
  "agent_id": "<uuid>",
  "page_size": 50
}

Query the last 10 audit events.

The response returns matched events plus a cursor. CLI, MCP, and dashboard use short enum tokens. The raw API uses full constants. Refer to enum rendering reference.

{
  "events": [{
    "event_id": "<uuid>",
    "event_type": "tool.call",
    "event_class": "governing",
    "stage": "completed",
    "result": "allowed",
    "occurred_at": "2026-05-30T10:30:00Z",
    "scope": { "kind": "workspace", "workspace_id": "ws_..." },
    "actor": { "kind": "agent", "id": "agent_..." },
    "primary_resource": { "kind": "tool_connection", "id": "conn_..." },
    "request_surface": { "surface": "gateway_mcp" },
    "correlation": { "trace_id": "0af7651916cd43dd8448eb211c80319c" },
    "payload": { "@type": "type.googleapis.com/dome.audit.v1.ToolCallV1", "toolName": "database-query" }
  }],
  "next_page_token": "..."
}

The pre-v1 total counter is gone. Use the cursor to walk the full result set.

Query events across an organization

Read audit across every tenant and workspace in one organization from an organization-scoped session or API key. Scope is derived from the authenticated identity; the request does not accept org_id. Set workspace_id only when you want to narrow an organization- or tenant-scoped read to one workspace.

GET /v1/audit/events?event_classes=EVENT_CLASS_GOVERNING&results=RESULT_DENIED&start_time=2026-07-01T00:00:00Z&page_size=100

QueryActivityChains remains workspace- and tenant-scoped. Org-scoped chains are not available yet.

CLI and MCP audit tools stay workspace-scoped today. Use the API (or an org-scoped platform key against QueryEvents) for org-wide reads.

Paginate results

Each response includes next_page_token. An empty token means the page was the last one.

dome audit query --limit 200
# ... copy the printed "Next page token: ..." value
dome audit query --limit 200 --page-token <token>

{ "page_size": 200, "page_token": "<token-from-previous-response>" }

Filter by class and result

Use class and result together to find denials, security signals, or audit access. Refer to event classes reference for the catalog.

# Every authorization deny in the workspace
dome audit query --classes governing --results denied

# All audit-access events — who looked at what
dome audit query --classes audit_access

# Failed logins and rejected agent-token exchanges
dome audit query --classes security --results denied --since 2026-06-01T00:00:00Z

Filter by actor and producer

Slice by who acted and which service emitted the event.

dome audit query --actor-kind scheduled_job
dome audit query --producer-service gateway --request-surface gateway_mcp

For a Gateway, use producer_gateway_id through the QueryEvents API.

Filter by resource

dome audit query \
  --primary-resource-kind rule_bundle \
  --primary-resource-id <bundle-uuid>

Reconstruct a request chain

Filter on a trace_id to return events from one request. Refer to correlation reference for the trace_id, operation_id, and parent_event_id contract.

dome audit query --trace-id 0af7651916cd43dd8448eb211c80319c

Filter by payload

Apply payload filters to a query.

# Every tool call that targeted database-query
dome audit query --payload-filter "tool.call:toolName=database-query"

# Multiple values, multiple filters
dome audit query \
  --payload-filter "tool.call:toolName=database-query,vector-search" \
  --types authorization.evaluate --results denied

Use the JSON form for exists:

dome audit query --payload-filter '[
  {"event_type":"tool.call","field":"toolName","operator":"exists"}
]'

Filter by time range

dome audit query \
  --since 2026-05-01T00:00:00Z \
  --until 2026-06-01T00:00:00Z

Get event

Retrieve a single audit event by ID. Scope is derived from the caller's session. There is no workspace_id argument.

dome audit get <event-id>

{ "event_id": "<uuid>" }

GET /v1/audit/events/<uuid>

Governing decision events that applied a loaded Rule bundle include decision provenance in the payload (bundle_etag, contributing_bundles, rule_id). The dashboard decision explainer deep-links those bundles to /rules/bundles?scope=<kind>&scopeId=<id>.

List activity chains

List activity chains in the active workspace. A chain is listed when any of its events matches the filter. Summary counts reflect the full chain. Refer to activity chains reference for their contract.

# Recent chains in the active workspace
dome audit chains --limit 20

# Chains that contain a denied governing event
dome audit chains --classes governing --results denied

# Chains for one agent in the last 24 hours
dome audit chains --agent-id agent_01HQ... --since 2026-06-05T00:00:00Z

{
  "chains": [{
    "activity_id": "case-12345",
    "workspace_id": "ws_...",
    "event_count": 47,
    "first_at": "2026-06-05T10:30:00Z",
    "last_at": "2026-06-05T10:34:21Z",
    "allowed_count": 41,
    "denied_count": 3,
    "error_count": 1,
    "agents": ["agent_..."],
    "event_types": ["tool.call", "authorization.evaluate"],
    "server_owned_count": 0,
    "caller_asserted_count": 47
  }],
  "next_page_token": ""
}

Get activity chain

Retrieve every event in one activity chain. Pass an activity_id to QueryEvents (or dome audit chain) to return events in cursor order.

# All events in one chain
dome audit chain case-12345

# Live tail one chain
dome audit stream --activity-id case-12345

# Filter the chain's events further
dome audit query --activity-id case-12345 --classes governing --results denied

Denied operations

A refusal is the denied result of the operation itself. For example, a refused tool invocation is event_type=tool.call, stage=completed, and result=denied. The shared denial block names why. There is no separate denial event type.

denial.reason is a closed vocabulary: permission_denied, wrong_caller_type, tenant_mismatch, unauthenticated, immutable_entity, service_disabled, policy_denied, stale_policy, guard_blocked, act_as_rejected, credential_required, rate_limited, oversize, quota_exceeded, plan_limit, billing_locked, subscription_canceled, and org_suspended.

Read denial.required_permission only when reason=permission_denied. Plan, quota, Guard, and identity refusals are not permission deficits.

Treat denial.detail as operator context, not a stable programmatic contract. Responses deliberately avoid exposing internal scope-resolution chains. Filter and automate on reason and, where present, required_permission.

# Every denied operation in the last hour
dome audit query --results denied --since 1h

# Denied tool calls caused by a stale tenant scope
dome audit query \
  --types tool.call \
  --results denied \
  --deny-reasons tenant_mismatch

# Guard-blocked tool and model calls
dome audit query \
  --types tool.call,model.call \
  --results denied \
  --deny-reasons guard_blocked

A tenant_mismatch row on a dashboard-initiated action almost always means the browser session's tenant scope drifted from the workspace's owning tenant — sign out and back in to re-scope the session.

Emit activity chain

Set activity_id on the emit side so events from one unit of work correlate. Pick an ID that maps to that unit, such as a case ID, job run, or conversation UUID. Chains are workspace-local, so human-meaningful IDs are safe.

export DOME_ACTIVITY_ID="case-12345"
dome agents register --name worker
dome rules deploy ./rules
dome audit query --limit 5
dome audit chain case-12345

with client.session() as session:
    page = client.control.query_audit_events(
        AuditQuery(event_types=("tool.call",), page_size=50),
    )
    event = client.control.get_audit_event(page.events[0].id)

GET /v1/audit/events
X-Dome-Activity-Id: case-12345

Migrate legacy event queries

Webhook subscriptions keep the public dome.webhook.v1 catalog. Do not rewrite webhook event names to audit names; where they differ, the webhook name remains authoritative on webhook deliveries.

Next steps

• Event catalog reference for every event type and its class
• Event contracts reference for the Audit v1 envelope, enum forms, and filter syntax
• Stream Live Events to stream events as they happen
• Export Data to ship retained records to SIEM and archival sinks
• Subscribe to Events to push signed events to external systems