# Export the audit log

The vault records every operation as an immutable audit event. You can query events with rich filters over the API and export them to CSV for archiving or SIEM ingestion.

See the full [Audit Logs API](/api-reference#tag/auditlogs) in the reference.

## List audit events (JSON)

```
GET /v1/audit-logs
```

This endpoint requires only the `Authorization` header (no nonce, timestamp, or assertion). The caller must have the `view_export_audit_log` capability.

**Query parameters:**

| Parameter | Type | Description |
|---|---|---|
| `format` | `json` or `csv` | Response format. Defaults to `json`. |
| `cursor` | integer | Opaque cursor for keyset pagination (use `next_cursor` from the previous response). |
| `limit` | integer (1-100) | Page size for JSON responses. |
| `start_time` | RFC 3339 datetime | Return events at or after this time. |
| `end_time` | RFC 3339 datetime | Return events before this time. |
| `topic` | `admin` or `signing` | Filter by event topic. |
| `status` | `pending`, `success`, or `failure` | Filter by event outcome. |
| `event_types` | string | Comma-separated list of event type names (see below). |
| `key_ids` | string | Comma-separated key IDs. Returns only events involving those keys. |
| `performed_by` | string | Comma-separated user IDs. Returns only events from those actors. |

**Example: fetch the last 10 signing failures for a specific key**

```bash
curl -s \
  "$CV_BASE/v1/audit-logs?topic=signing&status=failure&key_ids=my-key-id&limit=10" \
  -H "Authorization: ApiKey $API_KEY_UUID"
```

**JSON response shape:**

```json
{
  "items": [
    {
      "seq": 42,
      "event_type": "sign_request_failed",
      "topic": "signing",
      "status": "failure",
      "failure_reason": "Policy evaluation error",
      "performed_by": "my-trading-bot",
      "request_id": "req-abc123",
      "metadata": { "key_id": "my-key-id" },
      "raw_request": {},
      "logged_at": "2026-06-07T10:30:00Z",
      "completed_at": "2026-06-07T10:30:00.012Z"
    }
  ],
  "total": 142,
  "next_cursor": 41
}
```

## Export to CSV

Set `format=csv` to download all matching events as a CSV file. The CSV response ignores `cursor` and `limit` and returns every event matching the other filters.

**CSV columns:** `seq`, `request_id`, `event_type`, `topic`, `status`, `failure_reason`, `performed_by`, `key_id`, `logged_at`, `completed_at`.

```bash
curl -s \
  "$CV_BASE/v1/audit-logs?format=csv&start_time=2026-01-01T00:00:00Z&end_time=2026-02-01T00:00:00Z" \
  -H "Authorization: ApiKey $API_KEY_UUID" \
  -o january-audit.csv
```

## Event type reference

**User and group management:**
`user_created`, `user_updated`, `users_deleted`, `api_key_rotated`, `passkey_added`, `passkey_removed`, `passkey_reset`, `user_group_created`, `user_group_updated`, `user_groups_deleted`, `user_added_to_user_group`, `user_removed_from_user_group`, `security_group_created`, `security_group_updated`, `security_groups_deleted`, `keys_added_to_security_group`, `keys_removed_from_security_group`

**Key management:**
`key_created`, `key_imported`, `key_updated`, `keys_deleted`, `key_version_added`, `key_frozen`, `key_unfrozen`, `keys_backup_created`

**Signing:**
`sign_request_completed`, `sign_request_failed`, `sign_request_blocked_by_freeze`, `sign_request_blocked_by_policy`, `request_denied`

**Policy:**
`admin_policies_updated`, `admin_policy_created`, `admin_policy_updated`, `admin_policy_deleted`, `signing_policy_updated`

**Venue and auth:**
`venue_created`, `venue_updated`, `venues_deleted`, `failed_auth_attempt`

## Correlating events by request

The `request_id` field links the audit event back to the API call that triggered it. For async operations, the `request_id` in the audit log matches the `request_id` returned in the `202` response. For synchronous operations like signing, the `request_id` ties together the policy evaluation and the signing outcome in a single event.

To find all events for a specific operation, filter by `request_id` after retrieving the initial event.

## Forwarding to a SIEM

The CSV export is suitable for bulk ingestion into a SIEM. Schedule a recurring export job that pulls events from the last export's end time. The `seq` field is a monotonically increasing integer that you can use as a stable cursor: store the highest `seq` seen, then on the next run filter by `cursor` to continue from where you left off.

See [Audit retention & SIEM](/deploy/operations/audit-siem) for guidance on configuring audit log retention and shipping, and the [Audit Logs API](/api-reference#tag/auditlogs) for the full endpoint contract.