Skip to content
Docs menu

Admin API: logs, audit and alerts

Read the request log, run log queries, export requests and the audit log, set alerts and org webhooks, take backups and compliance packs, and manage shared, live and handed-off sessions over /api/admin/v1.

View .md

Everything the console shows about what happened in an org (requests, failures, the audit log, alerts, shared sessions) comes from these /api/admin/v1 routes. Use them to feed your own SIEM, to page someone from a webhook, to archive the audit log, or to build a support tool on top of an org's sessions.

Credentials and roles are on Venom Cloud APIs overview. Every route below answers in the scope of the caller: an org member sees their org, a key group admin key (vak_…) its key group, and the operator every org (narrow a listing with ?tenant=<org id>). Something outside the scope answers 404, never 403, so ids do not leak.

export VENOM_CLOUD=https://cloud.usevenom.dev
export ADMIN="Authorization: Bearer $VENOM_ADMIN_KEY"   # the admin token or a vak_ key

# the last 20 failed requests
curl -s "$VENOM_CLOUD/api/admin/v1/requests?status=error&limit=20" -H "$ADMIN"

# the same with the log query language, as NDJSON
curl -s "$VENOM_CLOUD/api/admin/v1/export?source=requests&format=ndjson&q=status:5xx%20since:24h" -H "$ADMIN" -o errors.ndjson

# audit rows about API keys, newest first
curl -s "$VENOM_CLOUD/api/admin/v1/audit?action=key&limit=100" -H "$ADMIN"

Request log

Route Permission What it does
GET /api/admin/v1/requests logs:read Request log rows, newest first: key, session, path, requested and served model, mode, served by (daemon or cloud), daemon, upstream, status, error code, route and fallback reason, attempts, tokens, cost_usd, ttft_ms, duration_ms, has_content.
GET /api/admin/v1/requests/{id} logs:read One request's trace (object: "venom.admin.trace"): the log row, every job with its candidates in cost order, timestamps (queued, dispatched, acked, first byte, finished, with hybrid-logical-clock stamps), the shared session of its root session when the caller may open one, and whether content is stored. {id} is req_<uuid>, else 400.
GET /api/admin/v1/requests/{id}/content content:read The stored request and response bodies, when the org logs content. Every read writes a content.viewed audit row. 503 vault_not_configured when the deployment has no vault.

Query parameters of GET /api/admin/v1/requests:

Parameter Default Meaning
key none a key id (uuid)
model none the requested model, exact
status none a status code (502), or error for every status ≥ 400 or row with an error code
daemon none a daemon id, or cloud for requests the cloud's providers served
provider none the upstream, exact
since, until none RFC 3339 times; until is exclusive
limit 200 1 to 500
tenant none operator only

When no content is stored, the trace's content.why says why: direct (a 307 request never passed through the cloud), no_vault, off (the org does not log content) or none.

Log queries

The console's log explorer runs on these routes. The query language (fields, operators, windows, pipes) is described in Log queries over the admin API and Log query language; this table lists the HTTP side. Every route needs logs:read. A key group admin key reads its key group's rows; an org member their org's; ?tenant= narrows the operator only.

Route Parameters What it returns
GET /api/admin/v1/logs/query q, cursor, limit (1–500, default 50), tz, tenant object: "venom.logs.query": the canonical query, diagnostics, the resolved window, and a result of kind rows (with next_cursor), table or timeseries, plus timings
GET /api/admin/v1/logs/suggest q, pos (UTF-16 offset; default the end), tenant completions at the cursor: replace span, items, context
GET /api/admin/v1/logs/fields none the field registry: name, aliases, type, description, examples, which fields can group, aggregate and sort
GET /api/admin/v1/logs/facets q, fields (comma list, at most 30), tz, tenant the top 10 values, distinct and missing counts of each field, or min/avg/p50/p95/p99/max for numbers, over the newest 20,000 matched rows (sample says when it sampled)
GET /api/admin/v1/logs/patterns q, tz, tenant the matched rows grouped into request shapes (variable tokens masked as <*>), at most 50, each with a count, a sparkline and a filter/exclude query
GET /api/admin/v1/logs/live q, cursor, tenant the live feed: rows that finished since the cursor (at most 100 a poll, the first poll covers the last hour), more, total, and on the first page a 30-minute spark. Poll it; it is not a stream
GET /api/admin/v1/logs/saved tenant the caller's saved queries and those shared in its scope, own first; each has mine
POST /api/admin/v1/logs/saved body {name, query, shared?, tenant_id?} save a query (stored canonical): 201
PATCH /api/admin/v1/logs/saved/{id} body {name?, query?, shared?} the author, or org:manage for a shared query
DELETE /api/admin/v1/logs/saved/{id} none the author, or org:manage for a shared query

next_cursor is opaque and pins the first page's window, so a relative window does not slide while you page. Send it back with the same q, tz and scope.

On the live feed, a developer or viewer sees only requests made with keys they created (the answer says own: true); owners, admins, key group admin keys and the operator see the whole scope. The live filter takes no pipes (400 live_pipeline), no window (live_window) and no content terms (live_content).

Error When
400 invalid_query the query does not parse; error.diagnostics and error.canonical say where
400 cursor_mismatch, 400 invalid_cursor a cursor from another query, time zone or scope; a malformed cursor
403 content_forbidden a content term (prompt:, response:, content:) without content:read
409 content_logging_off, 400 content_needs_org content search where the org does not log content; the operator searching content across orgs
409 name_taken, 409 too_many_saved_queries a saved query name in use; more than 200 saved queries per person
504 query_timeout the query ran past 5 seconds

Exports

GET /api/admin/v1/export streams a download, a page at a time. It needs org:manage plus logs:read (requests) or audit:read (audit log), and writes logs.exported or audit.exported to the audit log before the first byte.

Parameter Values Notes
source requests, audit required
format ndjson, csv NDJSON is application/x-ndjson, one object per line; CSV is RFC 4180 with a header line
q, tz, tenant requests only a log query without pipes (400 export_pipeline) or content terms (400 export_content_search); the query's window, default 24 hours; at most 50,000 rows
content=1 requests only adds request, response and content_truncated; needs content:read and one org with content logging on
since, until, action, actor audit only action is an action or its subject (content, key); at most 100,000 rows with columns id, ts, tenant_id, actor, action, target, detail

The response carries x-venom-export-limit with the row cap that applied.

Audit log

Route Permission What it does
GET /api/admin/v1/audit audit:read Audit rows, newest first: id, ts, tenant_id, actor, action, target, detail (redacted), and undone_by when an undo reversed it. Filters since, until (RFC 3339), action ([a-z0-9_.], up to 64), actor, target, q (text), before (a row id, for paging), limit (1–1000, default 1000). The answer is {data, next_before}; pass next_before as before for the next page. A team admin key sees rows it made or that name its team.
POST /api/admin/v1/audit/{id}/undo audit:read, then the permission of the original change Put a settings change back. The change is replayed backwards through the same operation, so its own checks apply (a viewer can undo nothing, a developer cannot undo a members change). Answers {object: "venom.audit.undo", undone, entry}; the new row carries undo_of.

Changes that can be undone include gears, prompt filters, budgets, the spend cap, pricing, routing modes, auto routing, content and session sharing settings, quality settings, member roles, key updates and scopes, and model access. Undo errors are 409: not_undoable (another kind of entry, no before/after, or a secret in it), already_undone, changed_since (the setting changed again after this entry: undo the newer one first).

Presence

GET /api/admin/v1/activity (daemons:read, ?tenant= for the operator) answers {object: "venom.admin.activity", window_s: 300, daemons, users}: the scope's daemons with an effective_state derived from heartbeats (enrolled, offline, draining, suspect, or their state), and the console users seen in the last 5 minutes.

Failure clusters

Route Permission What it does
GET /api/admin/v1/failures logs:read Failed and troubled sessions and requests grouped by cause (tool_error, loop, refusal, content_filter, timeout, provider_error, budget_block, allowlist_block, context_overflow, other): per cause the count, sessions, a daily series, kinds, 5 example sessions, the latest spike and the settings changes around it. days is 7 (default), 30 or 90; gear narrows.
GET /api/admin/v1/failures/settings logs:read The classifier: {classifier, gear, daily_cap}.
PUT /api/admin/v1/failures/settings org:manage {classifier: bool, gear, daily_cap} (daily_cap 1–500, default 50). Off by default. Audited failures.settings.
POST /api/admin/v1/failures/classify org:manage Run the classifier now, within the day's cap. Each label is one small, billed request on the gear's classifier model. 409 classifier_off while it is off.

Alerts

An alert is a saved log search the cloud runs every 5 minutes over the requests logged since its last run. A run that matches at least threshold requests records a hit and, when the org set one, posts it to the alert webhook. Reading needs audit:read; creating, changing, deleting and the webhook need org:manage (plus content:read for an alert that reads bodies). At most 50 alerts per org; hits are kept 90 days.

Route Body or parameters What it does
GET /api/admin/v1/alerts tenant data (the alerts), unread, webhook (its URL and the secret's last four characters), can_manage
POST /api/admin/v1/alerts {name, query, threshold?} or {builtin} create one. query is a plain search (no time terms, no pipes). Built-ins: secrets (a secret in a prompt), shell (shell tool use), large-prompt (prompts over 200k characters), errors (50 or more 5xx)
PATCH /api/admin/v1/alerts/{id} {name?, query?, threshold?, enabled?} change or pause it; resuming starts from now
DELETE /api/admin/v1/alerts/{id} none delete it
GET /api/admin/v1/alerts/hits alert, before, limit hits, newest first, each with unread for the caller; page with next_before
POST /api/admin/v1/alerts/seen none mark every hit so far as seen by the caller
PUT /api/admin/v1/alerts/webhook {url, rotate?} set the org's alert webhook. The signing secret (vwh_…) is made on the first save or with rotate: true and shown once
DELETE /api/admin/v1/alerts/webhook none remove it
POST /api/admin/v1/alerts/webhook/test none send one signed alert.test event

The alert webhook gets one POST per hit (5 seconds, no redirects, no retries) with venom-event: alert.hit, venom-delivery: <hit id> and the signature header described under Org webhooks. The body holds the alert, the count, the window, up to 50 request ids and console links, never a prompt or response:

{"type": "alert.hit", "id": "42", "created_at": "2026-11-03T09:00:00Z", "org": {"id": "…"},
 "alert": {"id": "…", "name": "Shell tool use", "query": "tool:(bash OR shell)", "threshold": 1, "detector": null},
 "count": 3, "truncated": false, "window": {"since": "…", "until": "…"},
 "request_ids": ["req_…"], "links": {"alert": "https://…", "explorer": "https://…", "requests": ["https://…"]}}

Org webhooks

An org's own HTTPS endpoints, told when something needs a person: spend, keys, daemons, filters, autoscaling, quality, SLAs, handoffs. Reading needs audit:read, changing needs org:manage. At most 10 endpoints per org; a legacy key group session (signed in with a vak_ key) has none (403). Events and deliveries are kept 30 days.

Route Body or parameters What it does
GET /api/admin/v1/webhooks tenant the org's endpoints: URL, events, description, enabled, the secret's last four characters
POST /api/admin/v1/webhooks {url, events, description?, tenant_id?} create one; 201 with secret (vwh_…), shown once
PATCH /api/admin/v1/webhooks/{id} {url?, events?, description?, enabled?, rotate?} change it; rotate: true returns a new secret once
DELETE /api/admin/v1/webhooks/{id} none delete it and its delivery log
POST /api/admin/v1/webhooks/{id}/test none send one signed webhook.test event now (one attempt, not retried)
GET /api/admin/v1/webhooks/deliveries endpoint, state (pending, delivered, failed), before (RFC 3339), limit (1–200, default 50) the delivery log, newest first, with status, error, attempts and latency; page with next_before
POST /api/admin/v1/webhooks/deliveries/{id}/retry none queue a failed or waiting delivery again with a fresh attempt count. 409 test_delivery, 409 already_delivered

url must be https, without credentials, at most 2,000 characters, and resolve to a public address (400 blocked_url otherwise; checked again at every delivery). description is at most 200 characters. 409 vault_not_configured when the deployment cannot seal the secret; 409 too_many_endpoints past 10.

Event types for events:

Group Types
spend spend_cap.warning, spend_cap.reached, budget.warning, budget.reached, spend.threshold, spend.forecast, spend.anomaly, chargeback.statement
keys key.expiring, key.expired, key_rotation.due, key_rotation.overdue, key_rotation.completed
models and providers model.retiring, price.changed, credits.expiring, quality.degraded, quality.recovered
daemons daemon.offline, daemon.online, autoscale.machine_added, autoscale.machine_joined, autoscale.machine_draining, autoscale.machine_removed, autoscale.machine_interrupted, autoscale.join_timeout, autoscale.cap_reached
filters prompt_filter.blocked, prompt_filter.response_blocked
SLAs sla.breach, sla.credit_drafted
sessions handoff.created, handoff.accepted, handoff.declined
Venom Tasks tasks.issue.created, tasks.issue.updated, tasks.issue.deleted, tasks.comment.created, tasks.issue.delegated
Venom Notes (never a personal vault) globe.note.created, globe.note.updated, globe.note.deleted (the org vault), globe.team_note.created, globe.team_note.updated, globe.team_note.deleted (team vaults)
Venom Experiments experiments.guardrail_breached, experiments.decided, experiments.started, experiments.ramped, experiments.stopped
Venom Flags flags.flag.created, flags.flag.updated, flags.flag.deleted
Venom People (org-wide people only) people.person.created, people.person.updated, people.person.removed
Venom Funnel (org-wide deals only) funnel.deal.created, funnel.deal.updated, funnel.deal.stage_changed, funnel.deal.archived
Venom Chat (public channels only) chat.channel.created, chat.channel.archived, chat.message.created
Teams org.team.created, org.team.updated, org.team.archived, org.team.member_added, org.team.member_removed
Status page status.incident.created, status.incident.updated, status.incident.resolved, status.maintenance.scheduled, status.maintenance.started, status.maintenance.completed, status.component.changed
Venom Incidents errors.issue.created, errors.issue.regressed, errors.alert.fired, incidents.created, incidents.updated, incidents.resolved, incidents.page
Venom Forms forms.response.created
test webhook.test (sent only by the test route)

Delivery and signature

Each event is a POST with content-type: application/json and these headers:

Header Value
venom-event the event type
venom-event-id the event id: use it as your idempotency key, since a delivery can arrive twice
venom-delivery the delivery id
venom-signature t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>" keyed by the secret>

The body is {id, type, created_at, org: {id}, data, links}: ids, names, numbers and console links, never a key, a secret or request content. A 2xx answer is delivered; anything else is retried after 1, 2, 4 … 128 minutes with ±20 % jitter (9 attempts, about 4 hours 15 minutes), then marked failed.

Check the signature before you trust a body: recompute the HMAC over the raw body, compare in constant time and refuse a t older than 5 minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyVenomWebhook(rawBody: string, header: string, secret: string, now = Date.now()): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(now / 1000 - t) > 300 || !parts.v1) return false;
  const want = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return want.length === parts.v1.length && timingSafeEqual(Buffer.from(want), Buffer.from(parts.v1));
}
import hashlib, hmac, time

def verify_venom_webhook(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > 300 or "v1" not in parts:
        return False
    want = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, parts["v1"])

The alert webhook uses the same scheme.

Backup and restore

Route Permission What it does
GET /api/admin/v1/backup org:manage (members:read too with members=1) The org's configuration as one versioned JSON bundle (format: "venom.org-backup", version: 1), as an attachment. Sections include teams, settings, gears, routing, model allowlists, filters, customers, budgets, library, memory, experiments, marketplace, alerts, webhooks, integrations, autoscaling, single sign-on and permission profiles. members=1 adds members and roles. Audited org.backup_exported.
POST /api/admin/v1/backup/restore org:manage (members:manage for members) {backup, dry_run?, on_conflict?, sections?, members?}. dry_run defaults to true: the answer is a plan per item (create, update with the differing fields, or skip with why). on_conflict: "keep" skips items that differ. A restore never deletes. Applied, it runs in one transaction and is audited org.backup_restored.

A bundle never holds a secret: no provider, GPU cloud or API keys, integration tokens, webhook secrets, the OIDC client secret or SCIM tokens, and no logs or usage. Its reenter list names what to enter again after a restore elsewhere. Webhooks come back turned off with new secrets, integrations as pending, and single sign-on turned off until a test sign-in. Sections whose page needs more than org:manage are skipped for callers without it: customers needs billing:manage, sso needs sso:manage. A bundle is at most 2 MiB. The CLI does the same with venom cloud backup and venom cloud restore.

Compliance pack

GET /api/admin/v1/compliance/export?since=YYYY-MM-DD&until=YYYY-MM-DD[&tenant_id=…] (org:manage) streams one signed ZIP of evidence for a period: members, teams, keys (never a key), spend by model, key, member and day, the models used and model access rules, provider keys (last four characters only), the controls in place and every change to them with before and after, the redacted audit log (up to 50,000 rows), incidents, signed session seals, a readable summary.html, manifest.json and an Ed25519 signature.json.

  • The period is two UTC days, inclusive, at most 366 days; ISO times work too. No period: the last 30 days.
  • The response is application/zip with x-venom-pack-sha256. Each download is audited compliance.exported with the hash.
  • It is signed with the org's policy-signing key, else the deployment's; with neither, 503 policy_signing_not_configured.
  • Verify it offline with venom compliance verify <pack.zip>.

Sessions

Captured sessions

Every request that carried x-venom-session is in the request log, so a session can be replayed without anyone sharing it. Metadata only: a request's body opens from its row (/requests/{id}/content).

Route Permission What it does
GET /api/admin/v1/captured-sessions logs:read Sessions in the request log, newest first. days (default 7, at most 30), q (text), limit (default 50, at most 200), tenant.
GET /api/admin/v1/captured-sessions/{session} logs:read One session's request log rows with the prompt and response filter rules that hit them, for the replay debugger.

Shared sessions

Traces members uploaded with venom session share (/v1/session-shares). visibility: "org" shows a share to everyone with logs:read; "admins" only to org:manage (and a key group admin key of the sharing key group).

Route Permission What it does
GET /api/admin/v1/session-shares logs:read (admins shares need org:manage) Shares, newest first, without traces. q, limit (default 100, at most 200), tenant.
GET /api/admin/v1/session-shares/{id} logs:read One share with its trace and comments. Audited session_share.viewed.
GET /api/admin/v1/session-shares/{id}/replay logs:read The share plus its session's request log rows (requests), for the replay debugger. Audited like a view.
PATCH /api/admin/v1/session-shares/{id} org:manage {title?, visibility?} (org or admins).
DELETE /api/admin/v1/session-shares/{id} org:manage Delete it and its comments.
GET /api/admin/v1/session-shares/{id}/comments logs:read Its comments.
POST /api/admin/v1/session-shares/{id}/comments logs:read {body, step?}: a comment, optionally on a step.
DELETE /api/admin/v1/session-shares/{id}/comments/{cid} the comment's author, or org:manage Delete a comment.
POST /api/admin/v1/session-shares/{id}/public org:manage {expires_in_days?}: a read-only public link (vss_…, shown once), 1 to the org's public_max_days (default 7, at most 30). Needs the org's public_links setting on. A new link replaces the old one.
DELETE /api/admin/v1/session-shares/{id}/public org:manage Revoke the public link.

Session summaries

The org's session history, when it collects summaries (off by default; the setting is PUT /api/admin/v1/settings/session-summaries).

Route Permission What it does
GET /api/admin/v1/session-summaries logs:read Summaries newest first, 50 a page with a next cursor. q is full text (words, "phrases", -not, or), member and repo are substrings, plus outcome (done, partial, failed, abandoned), min_cost, max_cost, days, before, limit. Also carries the org's setting and the last 30 days' count and cost.
GET /api/admin/v1/session-summaries/{id} logs:read One summary.
DELETE /api/admin/v1/session-summaries/{id} org:manage Delete it; audited.

Session guard pauses

Sessions the org's session guard paused (429 session_paused on their requests) because they ran too long or spent too much with no human message. The limits are GET/PUT /api/admin/v1/settings/session-guard.

Route Permission What it does
GET /api/admin/v1/session-pauses org:read Paused sessions, newest first; open=1 for the ones still paused.
POST /api/admin/v1/session-pauses/{id}/resume org:manage Resume one; its limits count from now. Audited session_guard.resume.

Live sessions

Sessions a member shares live with /share live, watched and co-driven from the console. Watching needs logs:read in the org, being in the share's audience and not being blocked; anything else is 404.

Route Who What it does
GET /api/admin/v1/live-sessions a watcher The live shares the caller may watch.
GET /api/admin/v1/live-sessions/{id} a watcher A long poll: after=<seq> and wait=<0..20> seconds. Answers what changed after seq (items by index, events, open permission prompts, viewers) and marks the caller present.
PATCH /api/admin/v1/live-sessions/{id} the owner, or org:manage Change grants and audience, as PATCH /v1/live-sessions/{id} does: {title?, audience?, invite?, drivers?, approvers?, block?, unblock?, revoke?, extend_minutes?}.
DELETE /api/admin/v1/live-sessions/{id} the owner, or org:manage Stop it; the transcript, events and inputs are deleted at once.
POST /api/admin/v1/live-sessions/{id}/inputs a driver or approver {kind: "message", text} (at most 8,000 characters), {kind: "approval", prompt_id, decision: "allow" | "deny", feedback?}, or while pairing {kind: "comment", text}. 202 {id, state: "queued"}.
POST /api/admin/v1/live-sessions/{id}/pass the driver, or the owner {to?: "owner" | "partner"}: hand the pairing driver token over (default the other side). 200 {driver, moved}.

Input errors: 403 not_a_driver, 403 approvals_not_granted, 409 prompt_closed, 403 prompt_blocked (an org prompt filter), and while pairing 403 not_the_driver, 409 driver_cannot_comment, 403 not_paired. An approval is always "allow once".

Handoffs

Sessions a member packaged for a teammate with /handoff. Recipients and the sender see a handoff; org:manage sees every one in the org.

Route Who What it does
GET /api/admin/v1/handoffs a member box=inbox (default; with open_count), sent, or all (org:manage).
GET /api/admin/v1/handoffs/{id} recipients, the sender, org:manage One handoff with its note, git summary and state.
POST /api/admin/v1/handoffs/{id}/decline a recipient {reason?}.
DELETE /api/admin/v1/handoffs/{id} the sender, or org:manage Cancel it.

Accepting happens on the recipient's machine (venom handoff accept <id>). Open handoffs expire after 14 days.

Errors

These routes use the admin error shape (type: "mesh_error") from Venom Cloud APIs overview. Common ones here: 403 forbidden (the role lacks the permission named in the message), 404 not_found (outside the caller's scope), 400 invalid_request (a bad field, named in the message), 409 conflicts listed in each section, 503 vault_not_configured.