Admin API
Read the orchestrator's live state, request log, sessions, spend, cache and pricing reports, and manage keys and config over /admin/v1.
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.
Related
- Operations for metrics and probes, Keys, budgets and limits.