---
title: Admin API
description: Read the orchestrator's live state, request log, sessions, spend, cache and pricing reports, and manage keys and config over /admin/v1.
section: orchestrator
order: 120
audience: [operator, builder, agent]
sources: [docs/architecture.md, services/go-orchestrator/internal/server/server.go, services/go-orchestrator/AGENTS.md]
features: [orchestrator.admin-overview, orchestrator.admin-anomalies, orchestrator.admin-upstreams, orchestrator.admin-shaping, orchestrator.admin-routes, orchestrator.admin-routing, orchestrator.admin-requests, orchestrator.admin-sessions, orchestrator.admin-shadow, orchestrator.admin-experiments, orchestrator.admin-spend, orchestrator.admin-usage, orchestrator.admin-pricing, orchestrator.admin-cache]
---

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.

```bash
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 {#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 {#log}

| 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 {#experiments}

| 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 {#spend}

| 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 {#manage}

| Endpoint | Page |
|---|---|
| `GET`, `POST /admin/v1/keys`; `PATCH`, `DELETE /admin/v1/keys/{id}` | [Keys, budgets and limits](/docs/orchestrator/keys-and-budgets.md#create) |
| `GET /admin/v1/intents`; `GET`, `PUT`, `DELETE /admin/v1/intents/{id}`; `PUT /admin/v1/teams/{team}/intent-cap` | [Keys, budgets and limits](/docs/orchestrator/keys-and-budgets.md#intents) |
| `POST /admin/v1/reload`; `GET /admin/v1/config/versions`; `GET /admin/v1/config/diff`; `POST /admin/v1/config/versions/{id}/rollback` | [Configuration reference](/docs/orchestrator/configuration.md#history) |
| `/admin/v1/local/*`, `/admin/v1/mesh/*`, `/admin/v1/daemon/*`, `GET /admin/v1/heal`, `/admin/v1/debug/pprof/` | [Operations](/docs/orchestrator/operations.md) |

## Errors {#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](/docs/orchestrator/operations.md) for metrics and probes, [Keys, budgets and limits](/docs/orchestrator/keys-and-budgets.md).
