> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domesystems.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit events

> Query audit events by class, result, actor, resource, correlation, and payload

export const auditEvent = "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.";

<p>
  {auditEvent}
</p>

Refer to [Audit events](/concepts/audit) 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:

1. [Query events](#query-events) with class, actor, resource, correlation, or payload filters.
2. [Get an event](#get-event) by ID when you need the full envelope.
3. [List](#list-activity-chains) or [get](#get-activity-chain) an activity chain, or [emit](#emit-activity-chain) 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](/operate/observe) uses the same permission. Batch and scheduled delivery live under [Export Data](/manage/export).

| 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.

<Callout icon="key">Requires `audit.view`.</Callout>

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.

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome audit query --limit 10
    ```

    <Callout icon="terminal">Reference: [`dome audit query`](/cli/operate/audit#query)</Callout>
  </Tab>

  <Tab title="MCP">
    Tool: `dome_audit_query`

    ```json theme={"system"}
    { "limit": 10 }
    ```

    <Callout icon="cpu">Reference: [`dome_audit_query`](/reference/mcp/audit#audit-query)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.audit.v1.Audit/QueryEvents
    Content-Type: application/json

    { "page_size": 10 }
    ```

    Filtered:

    ```json theme={"system"}
    {
      "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
    }
    ```

    <Callout icon="code">Reference: [`QueryEvents`](/api/audit/query-events)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Query recent audit events" theme={"system"}
    Query the last 10 audit events.
    ```
  </Tab>
</Tabs>

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#enum-rendering) reference.

```json theme={"system"}
{
  "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.

```bash theme={"system"}
dome audit query --limit 200
# ... copy the printed "Next page token: ..." value
dome audit query --limit 200 --page-token <token>
```

```json theme={"system"}
{ "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/events#event-classes) reference for the catalog.

```bash theme={"system"}
# 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.

```bash theme={"system"}
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](/api/audit/query-events).

### Filter by resource

```bash theme={"system"}
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/events#correlation) reference for the `trace_id`, `operation_id`, and `parent_event_id` contract.

```bash theme={"system"}
dome audit query --trace-id 0af7651916cd43dd8448eb211c80319c
```

### Filter by payload

Apply [payload filters](/reference/events#payload-filters) to a query.

```bash theme={"system"}
# 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`:

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

<Info>
  `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>`.
</Info>

### Filter by time range

```bash theme={"system"}
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.

<Callout icon="key">Requires `audit.view`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome audit get <event-id>
    ```

    <Callout icon="terminal">Reference: [`dome audit get`](/cli/operate/audit#get)</Callout>
  </Tab>

  <Tab title="MCP">
    Tool: `dome_audit_get_event`

    ```json theme={"system"}
    { "event_id": "<uuid>" }
    ```

    <Callout icon="cpu">Reference: [`dome_audit_get_event`](/reference/mcp/audit#audit-get-event)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.audit.v1.Audit/GetEvent
    Content-Type: application/json

    { "event_id": "<uuid>" }
    ```

    <Callout icon="code">Reference: [`GetEvent`](/api/audit/get-event)</Callout>
  </Tab>
</Tabs>

Governing decision events that applied a loaded Rule bundle include [decision provenance](/reference/events#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/events#correlation) reference for their contract.

<Callout icon="key">Requires `audit.view`.</Callout>

```bash theme={"system"}
# 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
```

<Callout icon="terminal">Reference: [`dome audit chains`](/cli/operate/audit#chains)</Callout>

```json theme={"system"}
{
  "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.

```bash theme={"system"}
# 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
```

<Callout icon="terminal">Reference: [`dome audit chain`](/cli/operate/audit#chain)</Callout>

## 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.

<Tabs>
  <Tab title="CLI">
    Set `--activity` (or `DOME_ACTIVITY_ID`) so every Connect RPC in the run carries `X-Dome-Activity-Id`.

    ```bash theme={"system"}
    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.
  </Tab>

  <Tab title="Python SDK">
    Wrap Dome API reads in `client.session()`. Pass an explicit ID to correlate work across processes.

    ```python theme={"system"}
    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)
    ```
  </Tab>

  <Tab title="HTTP">
    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.

    ```http theme={"system"}
    POST /dome.audit.v1.Audit/QueryEvents
    X-Dome-Activity-Id: case-12345
    ```
  </Tab>
</Tabs>

## Next steps

* [Events](/reference/events) reference for the Audit v1 envelope and event catalog
* [Stream Live Events](/operate/observe) to stream events as they happen
* [Export Data](/manage/export) to ship retained records to SIEM and archival sinks
* [Subscribe to Events](/operate/webhooks) to push signed events to external systems