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

# Audit Trail

> Immutable audit log of every governance action - required by EU AI Act Article 12

MeshAI records an immutable audit event for every governance action. Audit events cannot be modified or deleted once created. This satisfies EU AI Act Article 12 (record-keeping) requirements.

## Event Types

Event types actually emitted today:

| Event Type             | Description                                              |
| ---------------------- | -------------------------------------------------------- |
| `agent.registered`     | A new agent was registered                               |
| `agent.updated`        | Agent metadata was changed                               |
| `agent.deleted`        | An agent was removed                                     |
| `agent.blocked`        | An agent was blocked via the kill switch                 |
| `agent.unblocked`      | A kill-switch block was removed                          |
| `risk.classified`      | Risk classification was assigned or changed for an agent |
| `policy.created`       | A new policy was created                                 |
| `policy.updated`       | A policy was modified                                    |
| `policy.deleted`       | A policy was removed                                     |
| `anomaly.acknowledged` | An anomaly was acknowledged                              |
| `anomaly.resolved`     | An anomaly was resolved                                  |
| `api_key.created`      | A new API key was created                                |
| `team.updated`         | A team was updated                                       |
| `team.deleted`         | A team was removed                                       |

<Note>
  Some governance actions do not (yet) emit their own audit event - for example quarantine/release-quarantine, ABAC owner assignment/removal, and agent lifecycle changes. Check the specific feature page for what it actually records.
</Note>

## List Audit Events

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.meshai.dev/api/v1/audit-trail?limit=50" \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  from meshai import MeshAI

  client = MeshAI(api_key="msh_...")
  events = client.list_audit_events(limit=50)
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": 1042,
        "event_type": "agent.registered",
        "actor_type": "api_key",
        "actor_id": "key_abc123",
        "resource_type": "agent",
        "resource_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "description": "Agent registered: production-summarizer",
        "details": { "framework": "crewai" },
        "proxy_request_id": null,
        "created_at": "2026-03-17T10:00:00Z"
      },
      {
        "id": 1041,
        "event_type": "anomaly.acknowledged",
        "actor_type": "user",
        "actor_id": "admin@company.com",
        "resource_type": "anomaly",
        "resource_id": "789",
        "description": "Anomaly acknowledged",
        "details": { "anomaly_type": "cost_spike" },
        "proxy_request_id": null,
        "created_at": "2026-03-17T09:45:00Z"
      }
    ],
    "meta": { "total": 234, "page": 1, "limit": 50 }
  }
  ```
</ResponseExample>

## Filtering

Filter audit events by type, actor, resource, and time range using `start`/`end`:

<CodeGroup>
  ```bash curl theme={null}
  # By event type
  curl "https://api.meshai.dev/api/v1/audit-trail?event_type=agent.blocked" \
    -H "Authorization: Bearer msh_YOUR_API_KEY"

  # By resource (e.g. an agent)
  curl "https://api.meshai.dev/api/v1/audit-trail?resource_id=01ARZ3NDEKTSV4RRFFQ69G5FAV" \
    -H "Authorization: Bearer msh_YOUR_API_KEY"

  # By date range
  curl "https://api.meshai.dev/api/v1/audit-trail?start=2026-03-01T00:00:00Z&end=2026-03-17T23:59:59Z" \
    -H "Authorization: Bearer msh_YOUR_API_KEY"

  # Combined filters
  curl "https://api.meshai.dev/api/v1/audit-trail?event_type=anomaly.acknowledged&start=2026-03-01T00:00:00Z&limit=100" \
    -H "Authorization: Bearer msh_YOUR_API_KEY"
  ```

  ```python SDK theme={null}
  # By event type
  events = client.list_audit_events(event_type="agent.blocked")

  # By resource
  events = client.list_audit_events(resource_id="01ARZ3NDEKTSV4RRFFQ69G5FAV")

  # By date range
  events = client.list_audit_events(
      start="2026-03-01T00:00:00Z",
      end="2026-03-17T23:59:59Z",
  )
  ```
</CodeGroup>

Date ranges cannot exceed 180 days per request; free-tier tenants additionally have their window clamped to their retention period (see below).

## Export

Export audit events in CSV or JSON format for compliance reporting and external audit tools, using `fmt`:

<CodeGroup>
  ```bash curl (CSV) theme={null}
  curl "https://api.meshai.dev/api/v1/audit-trail/export?fmt=csv&start=2026-01-01T00:00:00Z" \
    -H "Authorization: Bearer msh_YOUR_API_KEY" \
    -o audit-trail.csv
  ```

  ```bash curl (JSON) theme={null}
  curl "https://api.meshai.dev/api/v1/audit-trail/export?fmt=json&start=2026-01-01T00:00:00Z" \
    -H "Authorization: Bearer msh_YOUR_API_KEY" \
    -o audit-trail.json
  ```

  ```python SDK theme={null}
  # Export as CSV
  csv_data = client.export_audit_events(fmt="csv", start="2026-01-01T00:00:00Z")

  # Export as JSON
  json_data = client.export_audit_events(fmt="json", start="2026-01-01T00:00:00Z")
  ```
</CodeGroup>

<Note>
  Export requires the Professional plan or above. Free and Starter tenants receive a `402` with an upgrade path.
</Note>

## Retention

| Plan            | Retention |
| --------------- | --------- |
| Free            | 7 days    |
| Starter         | 90 days   |
| Professional    | 395 days  |
| Enterprise      | Unlimited |
| Enterprise Plus | Unlimited |