Audit events

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

Overview

Audit v1 is the durable evidence trail for governed infrastructure. Stream Live Events shows the same record in real time. Export delivers retained history downstream. The typical workflow is:

Query events with class, actor, resource, correlation, or payload filters.
Get an event by ID when you need the full envelope.
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. Live streaming on Stream Live Events uses the same permission. Batch and scheduled delivery live under Export Data.

Default roles	Permission	Grants
All workspace roles	`audit.view`	Query events, get by ID, list and get activity chains

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.

Requires audit.view.

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.

CLI
MCP
API
Agent

dome audit query --limit 10

Reference: dome audit query

Tool: dome_audit_query

{ "limit": 10 }

Reference: dome_audit_query

POST /dome.audit.v1.Audit/QueryEvents
Content-Type: application/json

{ "page_size": 10 }

Filtered:

{
  "event_types": ["mcp.tool_call.completed", "mcp.tool_call.attempted"],
  "event_classes": ["EVENT_CLASS_GOVERNING"],
  "results": ["EVENT_RESULT_DENIED"],
  "agent_id": "<uuid>",
  "page_size": 50
}

Reference: QueryEvents

Query recent audit events

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": "mcp.tool_call.completed",
    "event_class": "governing",
    "result": "succeeded",
    "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.MCPToolCallCompletedV1", "tool": "database-query" }
  }],
  "next_page_token": "..."
}

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

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 "mcp.tool_call.completed:tool=database-query"

# Multiple values, multiple filters
dome audit query \
  --payload-filter "mcp.tool_call.completed:tool=database-query,vector-search" \
  --payload-filter "authorization.decision:decision=deny"

Use the JSON form for exists:

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

mcp.tool_call.* and llm.model_call.* payloads do not include request arguments by default. Contact support to enable argument capture on a workspace. Cedar rules still evaluate resource.arguments.<key>.

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.

Requires audit.view.

dome audit get <event-id>

Reference: dome audit get

Tool: dome_audit_get_event

{ "event_id": "<uuid>" }

Reference: dome_audit_get_event

POST /dome.audit.v1.Audit/GetEvent
Content-Type: application/json

{ "event_id": "<uuid>" }

Reference: GetEvent

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.

Requires audit.view.

# 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

Reference: dome audit chains

{
  "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,
    "filtered_count": 2,
    "error_count": 1,
    "agents": ["agent_..."],
    "event_types": ["mcp.tool_call.attempted", "mcp.tool_call.completed", "authorization.decision"],
    "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

Reference: dome audit chain

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.

CLI
Python SDK
HTTP

Set --activity (or DOME_ACTIVITY_ID) so every Connect RPC in the run carries X-Dome-Activity-Id.

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

--activity overrides DOME_ACTIVITY_ID. There is no implicit mint.

Wrap Dome API reads in client.session(). Pass an explicit ID to correlate work across processes.

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

Send X-Dome-Activity-Id on every Connect RPC. Dome stamps the ID with caller-asserted trust and strips the header before third-party LLM or MCP egress.

POST /dome.audit.v1.Audit/QueryEvents
X-Dome-Activity-Id: case-12345

Next steps

Events reference for the Audit v1 envelope and event catalog
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

Get started

Core concepts

Connect

Govern

Operate

Manage

Develop

Reference

Audit events

Overview

Requirements

Permissions

Query events

Paginate results

Filter by class and result

Filter by actor and producer

Filter by resource

Reconstruct a request chain

Filter by payload

Filter by time range

Get event

List activity chains

Get activity chain

Emit activity chain

Next steps

​Overview

​Requirements

​Permissions

​Query events

​Paginate results

​Filter by class and result

​Filter by actor and producer

​Filter by resource

​Reconstruct a request chain

​Filter by payload

​Filter by time range

​Get event

​List activity chains

​Get activity chain

​Emit activity chain

​Next steps

Overview

Requirements

Permissions

Query events

Paginate results

Filter by class and result

Filter by actor and producer

Filter by resource

Reconstruct a request chain

Filter by payload

Filter by time range

Get event

List activity chains

Get activity chain

Emit activity chain

Next steps