# Audit

Chaser provides an account-scoped audit event stream for tracking lifecycle actions.

## Query audit events

```bash
curl -sS "$CHASER_API_URL/v1/audit/events?action=workspace.create&limit=20" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "X-Chaser-Account: Acme Engineering" | jq
```

### Query parameters

| Parameter | Description |
|-----------|-------------|
| `action` | Filter by action (e.g., `session.create`, `workspace.delete`) |
| `resource_type` | Filter by resource type (e.g., `workspace`, `session`) |
| `resource_id` | Filter by specific resource ID |
| `status` | Filter by status (`success` or `failure`) |
| `before` | RFC 3339 cursor timestamp for pagination |
| `limit` | Max events to return (default 100, max 500) |

## Event shape

Each event includes:

| Field | Description |
|-------|-------------|
| `id` | Event ID |
| `actor_type` | Who performed the action |
| `actor_id` | Actor identifier |
| `action` | Action performed |
| `resource_type` | Type of resource affected |
| `resource_id` | Affected resource ID |
| `status` | `success` or `failure` |
| `summary` | Human-readable description |
| `metadata` | Additional context |
| `created_at` | Timestamp |

## Tracked actions

| Action | Description |
|--------|-------------|
| `session.create` | Session created |
| `session.terminate` | Session terminated |
| `session.exec` | Command executed |
| `workspace.create` | Workspace created |
| `workspace.delete` | Workspace deleted |
| `workspace.name.update` | Workspace renamed |
| `workspace.template.update` | Template mode changed |
| `workspace.snapshot.create` | Snapshot created |
| `workspace.snapshot.restore` | Snapshot restored |
| `workspace.snapshot.delete` | Snapshot deleted |
| `api_key.create` | API key created |
| `api_key.revoke` | API key revoked |
| `billing.account.update` | Billing configuration updated |
| `billing.checkout.create` | Checkout session created |

## Notes

- Events are scoped to the active account selected by `X-Chaser-Account`
- Scoped API keys must include `audit.read` to access this endpoint
- Service account keys can read audit events when granted `audit.read`