Audit logs

The audit log is an append-only record of who did what on the control plane. Every sensitive mutation — an agent 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. Entries are never modified or deleted; the log only grows.

The audit entry object

string

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

object

The principal that performed the action.

Show actor

string

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

string

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

string

The audited action (see Audited actions).

string

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

string | null

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

string

The x-request-id of the request that produced the entry — join this to your own logs and to the error envelope.

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

string

When the action occurred.

List audit logs

GET /v1/audit_logs returns entries newest-first. Cursor-paginated — see Pagination.

Filters

string

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

string

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

string

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

string

Lower bound (inclusive) on created_at, an RFC 3339 timestamp.

string

Upper bound (exclusive) on created_at, an RFC 3339 timestamp.

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

{
  "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 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 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 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 blocks a tool call (the persisted trace of a `403 forbidden`).
`credits.topped_up`	`credits`	A top-up succeeds.
`webhook.secret_rotated`	`webhook_endpoint`	A webhook signing secret is rotated.
`session.interrupted`	`session`	A running session is interrupted.

Each entry pins the exact request_id, so an audited action, its error envelope (if it failed), and your own request logs all correlate on one id. Money movements additionally carry an actor on the ledger, so spend is attributable without cross-referencing the audit log.

Introduction

Core resources

Platform

Identity

The audit entry object

List audit logs

Filters

Audited actions

​The audit entry object

​List audit logs

​Filters

​Audited actions

The audit entry object

List audit logs

Filters

Audited actions