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

# Workspace audit APIs

> Query and export workspace-scoped audit events.

Use these APIs for investigations, compliance exports, and operational tracing.

## GET `/v1/workspace/audit/events`

Returns workspace-scoped audit items.

### Query params

* `start_ms`, `end_ms`
* `agent_id`
* `action`
* `decision`
* `trace_id`
* `limit` (default 50, max 200)
* `cursor` (pagination)

<CodeGroup>
  ```bash curl theme={null}
  curl -sS "https://api.clawb.ai/api/v1/workspace/audit/events?agent_id=agt_123&limit=100" \
    -H "X-Clawb-Api-Key: ck_live_..."
  ```

  ```python Python SDK theme={null}
  from clawb_agent_sdk import ClawbClient, WorkspaceControlPlane

  client = ClawbClient(base_url="https://api.clawb.ai/api")
  control_plane = WorkspaceControlPlane(client=client, api_key="ck_live_replace_me")

  events = control_plane.workspace_audit_events(agent_id="agt_123", limit=100)
  print(events)
  ```
</CodeGroup>

### Example response

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "items": [
      {
        "event_id": "evt_01...",
        "created_at": "2026-02-28T00:00:00Z",
        "agent_id": "agt_123",
        "action": "refund",
        "decision": "deny",
        "trace_id": "trc_abc123",
        "policy_id": "pol_refunds_v2"
      }
    ],
    "next_cursor": "cur_01..."
  }
  ```
</CodeGroup>

## POST `/v1/workspace/audit/export`

Exports events as JSON or CSV.

### Request body

<CodeGroup>
  ```json JSON theme={null}
  {
    "format": "csv",
    "filters": {
      "start_ms": 1739952000000,
      "end_ms": 1740038399000,
      "decision": "deny"
    },
    "limit": 1000
  }
  ```

  ```bash curl theme={null}
  curl -sS -X POST "https://api.clawb.ai/api/v1/workspace/audit/export" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: ck_live_replace_me" \
    -d '{
      "format": "csv",
      "filters": {
        "start_ms": 1739952000000,
        "end_ms": 1740038399000,
        "decision": "deny"
      },
      "limit": 1000
    }'
  ```

  ```python Python SDK theme={null}
  from clawb_agent_sdk import ClawbClient, WorkspaceControlPlane

  client = ClawbClient(base_url="https://api.clawb.ai/api")
  control_plane = WorkspaceControlPlane(client=client, api_key="ck_live_replace_me")

  export_out = control_plane.workspace_audit_export(
      format="csv",
      filters={
          "start_ms": 1739952000000,
          "end_ms": 1740038399000,
          "decision": "deny",
      },
      limit=1000,
  )
  print(export_out)
  ```
</CodeGroup>

### Example response

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "format": "csv",
    "count": 128,
    "csv": "event_id,created_at,agent_id,action,decision\n..."
  }
  ```
</CodeGroup>

### Errors

* `401 {"error":"missing_api_key"}`
* `400 {"error":"invalid_format"}`
* `500 {"error":"audit_unavailable"}`