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

id · string

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

actor · object

The principal that performed the action.

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

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.

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.

​

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

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

Response

{
  "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	topup	A top-up 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 signing secret is rotated.
session.interrupted	session	A running session is interrupted.
app.db_rest	app	A database REST call runs as the service role. metadata carries the method and path.
app.db_migrated	app	A migration is applied to an app’s database.
app.bucket_created	app	A storage 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 lands. metadata.url is the address fetched.
browser.session_opened	browser_session	A browser is opened over REST — lazily, on the first action. An agent’s browser tool emits a browser.session.opened event 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 is minted for a browser session. metadata carries computer_id and expires_at, never the URL.
browser.context_saved	browser_context	A saved login is saved from a browser.
browser.context_granted	browser_grant	A saved login is granted to an agent or role.
browser.context_revoked	browser_context	A saved login is deleted, with every grant on it. metadata.context_id names it.
browser.credential_stored	vault_credential	A login credential is saved to a vault. metadata carries service and identity_id, never the secret.

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.