> ## 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.

# Audit logs

> A queryable, principal-attributed record of control-plane actions.

The **audit log** is an append-only record of who did what on the control plane. Every sensitive mutation — an [agent](https://vetta.sh/docs/api/agents.md) update, a key rotation, a role change, a denied policy, a credit top-up — is captured as an immutable entry attributed to the acting **principal** (a member or an API key). Use it to answer "who changed this, when, and from which request?" for security review, incident response, and compliance.

Reads require the `audit:read` [scope](https://vetta.sh/docs/api/authentication.md#scopes). Entries are never modified or deleted; the log only grows.

## The audit entry object

**id** `string`

Entry id (e.g. `aud_01H...`).

**actor** `object`

The principal that performed the action.

**actor**

**type** `string`

`user` (a member acting in the dashboard) or `key` (an API key acting programmatically).

**id** `string`

Id of the member (`usr_…`) or API key (`key_…`).

**action** `string`

The audited action (see [Audited actions](#audited-actions)).

**resource\_type** `string`

The kind of resource affected (e.g. `agent`, `api_key`, `member`, `webhook_endpoint`, `session`, `credits`).

**resource\_id** `string | null`

Id of the affected resource, when the action targets one.

**request\_id** `string`

The `x-request-id` of the request that produced the entry — join this to your own logs and to the [error envelope](https://vetta.sh/docs/api/errors.md).

**metadata** `object`

Action-specific detail (e.g. the before/after role on a role change, the `to_version` on a rollback, the denied tool on a policy denial).

**created\_at** `string`

When the action occurred.

## List audit logs

`GET /v1/audit_logs` returns entries newest-first. Cursor-paginated — see [Pagination](https://vetta.sh/docs/api/pagination.md).

### Filters

**actor** `string`

Filter to a single principal id (a member `usr_…` or key `key_…`).

**resource** `string`

Filter to a single resource id (e.g. a specific `agt_…`).

**action** `string`

Filter to one action string (e.g. `api_key.rotated`).

**request\_id** `string`

Filter to the entries one request wrote, by the `request_id` it carried.

**from** `string`

Lower bound (inclusive) on `created_at`: a date like `2026-08-01` or a timestamp like `2026-08-01T00:00:00Z` (send an offset's `+` as `%2B`). Anything else is `400 validation_failed` with `param: "from"`.

**to** `string`

Upper bound (exclusive) on `created_at`: a date like `2026-08-01` or a timestamp like `2026-08-01T00:00:00Z` (send an offset's `+` as `%2B`). Anything else is `400 validation_failed` with `param: "to"`.

```bash theme={"system"}
curl -fsSL "https://api.vetta.sh/v1/audit_logs?action=member.role_changed&from=2026-08-01T00:00:00Z" \
  -H "authorization: Bearer sk_live_..."
```

```json Response theme={"system"}
{
  "data": [
    {
      "id": "aud_01H9MM...",
      "object": "audit_entry",
      "actor": { "type": "user", "id": "usr_01H8AA..." },
      "action": "member.role_changed",
      "resource_type": "member",
      "resource_id": "mem_01H9JJ...",
      "request_id": "req_01H9MM...",
      "metadata": { "from_role": "member", "to_role": "admin" },
      "created_at": "2026-08-20T18:02:11Z"
    },
    {
      "id": "aud_01H9ML...",
      "object": "audit_entry",
      "actor": { "type": "key", "id": "key_01H8XK..." },
      "action": "api_key.rotated",
      "resource_type": "api_key",
      "resource_id": "key_01H8XK...",
      "request_id": "req_01H9ML...",
      "metadata": { "reason": "scheduled_rotation" },
      "created_at": "2026-08-20T17:59:40Z"
    }
  ],
  "has_more": true,
  "next_cursor": "aud_01H9ML..."
}
```

## Audited actions

The following control-plane actions are captured in the initial release. The list grows over time; treat `action` as an open string and branch on the prefixes you care about.

| Action | Resource | Recorded when |
| - | - | - |
| `agent.updated` | `agent` | An [agent](https://vetta.sh/docs/api/agents.md) configuration is changed (new version). |
| `agent.rolled_back` | `agent` | An agent is rolled back to a prior version. `metadata.to_version` carries the target. |
| `api_key.created` | `api_key` | A new [API key](https://vetta.sh/docs/api/authentication.md) is issued. |
| `api_key.rotated` | `api_key` | A key's secret is rotated. |
| `api_key.revoked` | `api_key` | A key is revoked. |
| `member.role_changed` | `member` | A [member's](https://vetta.sh/docs/api/organizations.md) role changes. `metadata` carries `from_role`/`to_role`. |
| `member.removed` | `member` | A member is removed (triggering the removal cascade). |
| `policy.denied` | `session` | A [permission policy](https://vetta.sh/docs/api/agents.md) blocks a tool call (the persisted trace of a `403 forbidden`). |
| `credits.topped_up` | `topup` | A [top-up](https://vetta.sh/docs/api/credits.md) succeeds, or free credit is granted to your balance. `metadata.source` says which kind of grant it was. |
| `credits.adjusted` | `ledger_entry` | Support corrects your balance downward. `metadata.amount_micro_usd` is the (negative) amount and `metadata.note` the reason. |
| `webhook.secret_rotated` | `webhook_endpoint` | A [webhook](https://vetta.sh/docs/api/webhooks.md) signing secret is rotated. |
| `session.interrupted` | `session` | A running [session](https://vetta.sh/docs/api/sessions.md) is interrupted. |
| `app.db_rest` | `app` | A [database REST](https://vetta.sh/docs/api/database.md) call runs as the service role. `metadata` carries the method and path. |
| `app.db_migrated` | `app` | A [migration](https://vetta.sh/docs/api/database.md) is applied to an app's database. |
| `app.bucket_created` | `app` | A [storage](https://vetta.sh/docs/api/storage.md) bucket is created. `metadata.bucket` names it. |
| `app.bucket_deleted` | `app` | A storage bucket is deleted (with `metadata.force` when it was emptied first). |
| `app.storage_put` | `app` | An object is written — inline, through a signed upload URL (`metadata.signed`), or by an agent's `storage_put`. `metadata` carries `bucket` and `key`, never the bytes. |
| `app.storage_get` | `app` | An object is read, or a signed download URL issued (`metadata.signed`). |
| `app.storage_deleted` | `app` | An object is deleted. |
| `file.imported` | `file` | A [URL import](https://vetta.sh/docs/api/files.md#import-a-file-from-a-url) lands. `metadata.url` is the address fetched. |
| `browser.session_opened` | `browser_session` | A [browser](https://vetta.sh/docs/api/browser.md) is opened over REST — lazily, on the first action. An agent's `browser` tool emits a `browser.session.opened` [event](https://vetta.sh/docs/api/events.md) instead. |
| `browser.session_closed` | `browser_session` | A REST-opened browser is closed and its minutes settled. |
| `browser.live_view_opened` | `browser_session` | A [live view](https://vetta.sh/docs/api/browser-sessions.md#open-a-live-view) is minted for a browser session. `metadata` carries `computer_id` and `expires_at`, never the URL. |
| `browser.context_saved` | `browser_context` | A [saved login](https://vetta.sh/docs/api/browser.md#save-a-login) is saved from a browser. |
| `browser.context_granted` | `browser_grant` | A saved login is [granted](https://vetta.sh/docs/api/browser.md#grant-a-saved-login) to an agent or role. |
| `browser.context_revoked` | `browser_context` | A saved login is [deleted](https://vetta.sh/docs/api/browser.md#revoke-a-saved-login), with every grant on it. `metadata.context_id` names it. |
| `browser.credential_stored` | `vault_credential` | A login [credential is saved](https://vetta.sh/docs/api/browser.md#save-a-credential) to a vault. `metadata` carries `service` and `identity_id`, never the secret. |

> [!NOTE]
>
> Each entry pins the exact `request_id`, so an audited action, its [error envelope](https://vetta.sh/docs/api/errors.md) (if it failed), and your own request logs all correlate on one id. Money movements additionally carry an `actor` on the [ledger](https://vetta.sh/docs/api/credits.md#ledger), so spend is attributable without cross-referencing the audit log.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.