Skip to content
Docs menu

Admin API

Read the orchestrator's live state, request log, sessions, spend, cache and pricing reports, and manage keys and config over /admin/v1.

View .md

Everything the web console shows comes from /admin/v1/*: JSON, snake_case, Authorization: Bearer $VENOM_ADMIN_TOKEN on every call (unset token: 503; wrong token: 401). Use it to build your own dashboards, alerting or billing on top of the orchestrator.

export ADMIN="Authorization: Bearer $VENOM_ADMIN_TOKEN"
curl -s http://127.0.0.1:8787/admin/v1/overview -H "$ADMIN"
curl -s "http://127.0.0.1:8787/admin/v1/requests?limit=20" -H "$ADMIN"
curl -s "http://127.0.0.1:8787/admin/v1/spend?from=2026-11-01&to=2026-11-03&team=acme" -H "$ADMIN"

The full request and response shapes are generated from the contract in the API reference (/docs/api/orchestrator). This page says what each endpoint is for.

Live state

Endpoint What it returns
GET /admin/v1/overview Since start, in memory: requests, errors, tokens (in, out, cached, cache writes), cache hit ratio, cost, latency and TTFT p50/p95, active streams, per-model figures, and wasted spend (billed attempts whose output was discarded) by model and reason.
GET /admin/v1/anomalies Open cost anomalies, newest first: a key or session whose spend per hour or cache-break ratio is far above its baseline.
GET /admin/v1/upstreams Each upstream: kind, base URL, disabled (and why), healthy, breaker state (closed, open, half_open), in-flight count, latency, models, last error, local, retry-budget figures, models in a quota cooldown, engine load (queue, KV-cache use, saturated) and its rate shaper.
GET /admin/v1/shaping Every upstream's learned provider rate limits (requests and tokens: limit, remaining, reset), queue depth, admitted, queued, cancelled and rejected counts, and wait percentiles.
GET /admin/v1/routes Each alias with its strategy and targets in order: weight, available (with reason and fix when the upstream lacks the model), servable now, context window, live TTFT estimate and capabilities. Experiments show their variants.
GET /admin/v1/routing[?window=24h&key=NAME&alias=a,b&recent=10] The GET /v1/routing view over every key (?key= narrows it), with each fallback's key, plus the learned scores for strategy: learned aliases. The console's Routing page.

Request log and sessions

Endpoint What it returns
GET /admin/v1/requests?limit=100 (max 1000) Newest first: requested model and route, the upstream and upstream_model that served, status, stream, latency and TTFT, tokens (in, out, cached, cache writes), attempts and attempt_log, error, session and parent session, cost_usd and where its price came from (custom, base_model, builtin, local, unpriced), variant, profile, role, gear, tools, cache-break reason, wasted tokens and USD with a breakdown, cache savings, audio_chars and audio_ms.
GET /admin/v1/sessions?limit=50 (max 500) Per-session aggregates over the request log: requests, errors, tokens, cost, models, subagents (rolled up by x-venom-parent-session).
GET /admin/v1/sessions/{id}?limit=1000[&subagent_requests=1] (max 5000) One session and its requests. The venom CLI's /cost reads it.
POST /admin/v1/sessions/{id}/outcome {success: bool, score?: number}: record how a session went. Experiments and strategy: learned score targets from these; the eval runner sends them.

The request log keeps defaults.request_log_retention rows (100,000 by default); the spend ledger is separate and never pruned.

Experiments and shadow traffic

Endpoint What it returns
GET /admin/v1/experiments Every experiment alias with its variants (name, target, weight).
GET /admin/v1/experiments/{alias}?since=<RFC 3339> Per variant: sessions, outcomes, success rate, cost, latency, so you can compare.
GET /admin/v1/shadow?days=7&route=<alias>&limit=50 Per shadowed route and candidate: agreement with the primary, latency p50s, cost, sample outcomes (replayed, dropped, capped), and recent samples.

Spend, cache and pricing

Endpoint What it returns
GET /admin/v1/spend?from=&to=&key=&team=&sessions=20 The spend ledger for UTC days from..to (YYYY-MM-DD, default the last 30 days, at most 366): totals and breakdowns by_key, by_team, by_model (with each model's base model), by_base_model, by_day, per service tier with savings, and the costliest sessions. key= and team= narrow every list.
GET /admin/v1/usage/by-role?since=7d&until= Spend per lane (x-venom-role: workers, smart, vision, …; unnamed requests are main), from the request log. since is RFC 3339, a UTC day or a duration back (7d, 36h).
GET /admin/v1/cache?days=7&sessions=10 The prompt-cache report: hit ratio, cached, written and uncached tokens with their cost and savings, by route, model, upstream and day, cache-break reasons, and the sessions with the most breaks.
GET /admin/v1/pricing Every configured model's effective price (USD per 1M tokens), its source, the blended price strategy: cheapest ranks by, each route's targets in price order, and the enabled cloud models nothing prices (booked at $0).

Keys, intents and config

Endpoint Page
GET, POST /admin/v1/keys; PATCH, DELETE /admin/v1/keys/{id} Keys, budgets and limits
GET /admin/v1/intents; GET, PUT, DELETE /admin/v1/intents/{id}; PUT /admin/v1/teams/{team}/intent-cap Keys, budgets and limits
POST /admin/v1/reload; GET /admin/v1/config/versions; GET /admin/v1/config/diff; POST /admin/v1/config/versions/{id}/rollback Configuration reference
/admin/v1/local/*, /admin/v1/mesh/*, /admin/v1/daemon/*, GET /admin/v1/heal, /admin/v1/debug/pprof/ Operations

Errors

Admin errors are JSON with an error message (most endpoints) or OpenAI's {"error": {message, type, code}} (local models, mesh and daemon). A bad query parameter is 400, an unknown id 404.