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

# vetta audit

> Query the principal-attributed control-plane audit trail.

The audit log is a queryable, principal-attributed record of control-plane actions: keys created, rotated and revoked; roles changed; agents updated and rolled back; credits topped up; webhook secrets rotated; sessions interrupted.

Requires the `audit:read` scope.

## Commands

| Command            | Description                                                             |
| ------------------ | ----------------------------------------------------------------------- |
| `vetta audit list` | List audit entries, filtered by actor, resource, action, or date range. |

## list

```bash theme={"system"}
vetta audit list --limit 2
```

```json theme={"system"}
{
  "data": [
    {
      "id": "aud_r9h66ppwspk4jg8831qjc13wjt",
      "object": "audit_entry",
      "actor": { "type": "key", "id": "key_66nnedy98yfx3ygzssfv99p7tf" },
      "action": "api_key.created",
      "resource_type": "api_key",
      "resource_id": "key_gwpjrs1egky00g6vw5gjczj6fs",
      "request_id": "req_8mrnm932dm47n432bmyq6ebz9v",
      "metadata": {
        "scopes": ["agents:write", "agents:read", "sessions:write", "billing:read"]
      },
      "created_at": "2026-08-22T23:56:53.633Z"
    }
  ],
  "has_more": true,
  "next_cursor": "aud_4jkqe0h2z8zaams2g02y077ahe"
}
```

| Flag              | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| `--actor`         | Filter by the principal that acted — a `key_` or `usr_` id.     |
| `--resource`      | Filter by the resource id acted on (`agt_`, `key_`, `whk_`, …). |
| `--action`        | Filter by action name, e.g. `agent.updated`, `api_key.rotated`. |
| `--from` / `--to` | ISO-8601 date or timestamp bounds.                              |
| `--limit`         | Page size.                                                      |
| `--after`         | Cursor from a previous page's `next_cursor`.                    |

Every entry carries `request_id`, so an audit row joins directly to the API request that produced it.

```bash theme={"system"}
vetta audit list --action api_key.created --from 2026-08-01 --human
```

## Paging the whole trail

```bash theme={"system"}
CURSOR=""
while :; do
  PAGE=$(vetta audit list --limit 100 ${CURSOR:+--after "$CURSOR"})
  echo "$PAGE" | jq -c '.data[]'
  [ "$(echo "$PAGE" | jq -r .has_more)" = "true" ] || break
  CURSOR=$(echo "$PAGE" | jq -r .next_cursor)
done
```