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

> Query, inspect, and export audit events

Audit tools provide access to the Dome Platform audit trail. Query events by type, agent, or time range, inspect individual events, and export records for external analysis. These 4 tools require workspace context.

Tool results render enum fields as short tokens (`governing`, `denied`, `gateway_mcp`), and filter arguments accept those same tokens. Refer to [Enum rendering](/reference/events#enum-rendering) reference.

<Note>
  Audit reads are scoped to the active workspace. The server checks the workspace-level `audit.view` permission, so a workspace member can read their own workspace's audit even without a tenant role. Tenant- or org-scoped API keys reading without a workspace context fall back to the tenant-level `audit.view`.
</Note>

## Audit Query

`dome_audit_query`

Query audit events with optional filters. Returns events with type, agent, timestamp, and data.

| Parameter               | Type    | Required | Description                                                               |
| ----------------------- | ------- | -------- | ------------------------------------------------------------------------- |
| `agent_id`              | string  | No       | Filter by agent ID                                                        |
| `type` / `types`        | string  | No       | Event types, comma-separated                                              |
| `classes`               | string  | No       | `governing`, `state_change`, `security`, `audit_access` (comma-separated) |
| `results`               | string  | No       | Event results, comma-separated                                            |
| `agent_ids`             | string  | No       | Multiple agent IDs, comma-separated                                       |
| `primary_resource_id`   | string  | No       | Primary resource ID                                                       |
| `primary_resource_kind` | string  | No       | Primary resource kind                                                     |
| `trace_id`              | string  | No       | Every event for one request                                               |
| `activity_id`           | string  | No       | Every event in one [activity chain](/reference/events#correlation)        |
| `operation_id`          | string  | No       | Multi-event operation ID                                                  |
| `parent_event_id`       | string  | No       | Children of a given event                                                 |
| `actor_kind`            | string  | No       | Actor kind                                                                |
| `actor_id`              | string  | No       | Actor ID                                                                  |
| `producer_service`      | string  | No       | Producer service                                                          |
| `producer_gateway_id`   | string  | No       | Producer Gateway ID                                                       |
| `request_surface`       | string  | No       | Origin surface                                                            |
| `caller_surface`        | string  | No       | Caller application surface                                                |
| `payload_filter`        | string  | No       | `event.type:field=value`, semicolon-separated or JSON array               |
| `since`                 | string  | No       | Start time (RFC3339)                                                      |
| `until`                 | string  | No       | End time (RFC3339)                                                        |
| `limit`                 | number  | No       | Maximum results (default: 50)                                             |
| `page_token`            | string  | No       | Cursor from a previous call                                               |
| `compact`               | boolean | No       | Bounded investigation rows without full payload (default: false)          |

**Permission:** `audit.view`

```json title="Example tool call" theme={"system"}
{
  "name": "dome_audit_query",
  "arguments": {
    "type": "agent.registered,agent.suspended",
    "limit": 10,
    "since": "2025-01-01T00:00:00Z"
  }
}
```

Returns events in reverse chronological order. Each event includes an ID, type, timestamp, actor, and event-specific details.

## Audit Get Event

`dome_audit_get_event`

Get a single audit event by its ID.

| Parameter  | Type   | Required | Description    |
| ---------- | ------ | -------- | -------------- |
| `event_id` | string | Yes      | Audit event ID |

**Permission:** `audit.view`

```json title="Example tool call" theme={"system"}
{
  "name": "dome_audit_get_event",
  "arguments": {
    "event_id": "evt_01HQXYZ..."
  }
}
```

Returns the full event record including all metadata, the acting principal, and the complete event payload.

## Audit Export

`dome_audit_export`

Export audit events in a SIEM-friendly format for external processing or archival. Supports the same filters as `dome_audit_query`, plus a `format` selector.

| Parameter  | Type   | Required | Description                                             |
| ---------- | ------ | -------- | ------------------------------------------------------- |
| `agent_id` | string | No       | Filter by agent ID                                      |
| `type`     | string | No       | Filter by event type (comma-separated for multiple)     |
| `since`    | string | No       | Start time (RFC3339)                                    |
| `until`    | string | No       | End time (RFC3339)                                      |
| `limit`    | number | No       | Maximum results (default: 1000)                         |
| `format`   | string | No       | Output format: `jsonl` (default), `json`, `ocsf`, `cef` |

**Permission:** `audit.export`

| Format  | When to use                                      |
| ------- | ------------------------------------------------ |
| `jsonl` | NDJSON, one event per line — log shippers, `jq`. |
| `json`  | Single pretty array — archival.                  |
| `ocsf`  | OCSF v1.1.0 JSON — Splunk, Sentinel, Chronicle.  |
| `cef`   | Common Event Format — ArcSight, QRadar, syslog.  |

```json title="Example tool call" theme={"system"}
{
  "name": "dome_audit_export",
  "arguments": {
    "since": "2025-01-01T00:00:00Z",
    "until": "2025-02-01T00:00:00Z",
    "limit": 5000,
    "format": "ocsf"
  }
}
```

<Info>
  The same format set is available on `dome audit export --format` and on the file-based export connectors in [Export Data](/manage/export).
</Info>

## Audit Usage

`dome_usage`

Show LLM token consumption and a per-class estimated cost for the active workspace over the last 24 hours. Use it when an assistant needs to summarize workspace spend, build a budget guardrail, or confirm token attribution.

This tool takes no parameters — it always reports the active workspace over the last 24 hours. For dimensional breakdowns (per-agent, per-API-key, per-identity, per-model), read the [REST query surface](/operate/observe#token-usage-and-cost) directly.

**Permission:** `audit.view`

```json title="Example tool call" theme={"system"}
{
  "name": "dome_usage",
  "arguments": {}
}
```

Returns the workspace token summary as JSON:

```json theme={"system"}
{
  "llm_input_tokens": 412000,
  "llm_cache_read_tokens": 1820000,
  "llm_cache_write_tokens": 88000,
  "llm_output_tokens": 64000,
  "llm_reasoning_tokens": 12000,
  "llm_total_tokens": 2396000,
  "estimated_cost_usd": 3.4521
}
```

<Note>
  The estimated cost is a blended cross-model rate intended for trend-watching, not a billable figure. Refer to [Token Usage and Cost](/operate/observe#token-usage-and-cost) for the full token-class breakdown.
</Note>

## Next steps

Prefer the Operate how-tos for query patterns. This page is the tool surface:

* [Audit events](/operate/audit)
* [Stream Live Events](/operate/observe)
* [Events](/reference/events) reference