Admin API: usage, budgets and spend
Read your org's usage and costs, set spend guards and alerts, forecast the month, find savings, produce chargeback statements and reconcile provider invoices over /api/admin/v1.
These routes are the money side of the console: what your org spent and on what, the guards that stop or downgrade spend, alerts and forecasts, savings you have not taken yet, monthly chargeback statements per key group or project, and checks of a provider's invoice against what Venom booked. Use them to feed your own finance dashboards, to bill internal teams, or to let an agent watch spend.
Every route takes an admin credential (who can use the admin API). The
operator token reads every org: add ?tenant=<org id> to a read, or tenant_id to a write body. A key group admin key
(vak_…) sees its own key group where the table says so. Errors follow the common shape.
A key group holds API keys, daemons, policies and GPU grants, not people. The API keeps the name team: a
team scope, group=team and the team-savings route are about key groups.
A first call
export VENOM_CLOUD=https://cloud.usevenom.dev
export ADMIN="Authorization: Bearer $VENOM_CLOUD_ADMIN_TOKEN" # or a vak_ key
# Spend for the last 7 days, per key, day and model
curl -s "$VENOM_CLOUD/api/admin/v1/usage?days=7" -H "$ADMIN"
# A $500 monthly cap on one key group that downgrades to a cheaper model instead of refusing
curl -s "$VENOM_CLOUD/api/admin/v1/budgets" -H "$ADMIN" -H "Content-Type: application/json" -d '{
"scope": "team", "subject": "<key group id>", "period": "month",
"limit_usd": 500, "soft_pct": 80, "action": "downgrade", "downgrade_model": "gpt-4.1-mini"
}'const base = "https://cloud.usevenom.dev/api/admin/v1";
const headers = { Authorization: `Bearer ${process.env.VENOM_CLOUD_ADMIN_TOKEN}` };
const forecast = await fetch(`${base}/spend-forecast?period=month`, { headers }).then((r) => r.json());
const csv = await fetch(`${base}/chargeback?period=last_month&group=project&format=csv`, { headers }).then((r) => r.text());import os, requests
base = "https://cloud.usevenom.dev/api/admin/v1"
h = {"Authorization": f"Bearer {os.environ['VENOM_CLOUD_ADMIN_TOKEN']}"}
statement = requests.get(f"{base}/chargeback", params={"period": "this_month", "group": "team"}, headers=h).json()Amounts in responses are USD unless a field says otherwise (*_nusd fields are nano-dollars). Days are UTC.
Usage
| Route | Permission | What it returns |
|---|---|---|
GET /api/admin/v1/usage |
usage:read |
?days= (1 to 92, default 31). Per key, UTC day and model: requests, tokens in and out, cached tokens, cost_usd, local. Also tiers (what each service tier billed and saved), cache (the prompt-cache report by model and gear, and why misses happened), partial (responses cut short because the client left), escalations (work retried on a stronger tier in the last 7 days) and approx (rankings and distinct sessions from sketches, labelled approximate). A vak_ key sees its own key group |
GET /api/admin/v1/usage/tasks |
usage:read |
Cost per task (the x-venom-task header): ?days=7|30|90 (default 30). With &task=<task>: one task's sessions, models, roles, members and days. A vak_ key sees its own key group |
GET /api/admin/v1/usage/outcomes |
usage:read |
Cost per outcome: spend per merged pull request and closed issue, this window against the one before. ?days=7|30|90 (default 30) |
GET /api/admin/v1/usage/diet |
usage:read |
The token diet: the biggest sources of avoidable input tokens, each with a fix. ?days=7|30|90 (default 30) |
Budgets (spend guards)
A budget caps spend for one subject over a period. At soft_pct of the limit, requests carry
x-venom-spend-warning and a notification is written. At the limit, action: block refuses requests with
429 spend_limit_reached (the error names the budget and a suggested_model), and action: downgrade sends them
to downgrade_model with x-venom-spend-downgrade. See Rate limits and budgets.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/budgets |
usage:read (or a manage permission) |
?period=day|month (default month): every budget with live spend, state, a forecast, the per-member and per-gear breakdowns, and the last 20 warning and limit events |
POST /api/admin/v1/budgets |
billing:manage or org:manage |
Create one; 201 with the budget. Audited budget.created |
PATCH /api/admin/v1/budgets/{id} |
billing:manage or org:manage |
Change limit_usd, soft_pct, action, downgrade_model or name. scope, subject and period are fixed: delete and recreate |
DELETE /api/admin/v1/budgets/{id} |
billing:manage or org:manage |
Remove it. Another org's id answers 404 |
Body of POST:
| Field | Type | Default | Rule |
|---|---|---|---|
scope |
string | required | member, key, team, gear, customer or project |
subject |
string | required | a member's user id, a key id (the budget covers the key's whole rotation chain), a key group id (team), a gear name, a customer id or a project tag |
period |
string | required | day, month, or total (no reset; only for project) |
limit_usd |
number | required | 0 to 10,000,000 |
soft_pct |
integer | 80 | 1 to 100 |
action |
string | block |
block or downgrade |
downgrade_model |
string | none | required with downgrade; a model id, at most 200 characters |
name |
string | a label from the subject | at most 160 characters |
One budget per subject and period: a second answers 409 conflict. Unknown fields answer 400.
Spend alerts
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/spend-alerts |
usage:read |
The org's spend notifications, newest first, with unread for the caller; the alert settings; where alerts go (the console and org webhooks; there is no email). Pages with ?limit= (1 to 100, default 30) and ?before=<id> |
POST /api/admin/v1/spend-alerts/seen |
usage:read |
Marks every notification so far as seen for the caller (the console's bell count goes to 0). Body {tenant_id?} |
PUT /api/admin/v1/spend-alerts/settings |
billing:manage or org:manage |
Change the rules; omitted fields keep their value. Audited spend_alerts.updated |
Settings fields:
| Field | Type | Default | Meaning |
|---|---|---|---|
enabled |
boolean | true |
alerts on or off |
thresholds |
number[] | [50, 80, 100] |
percents of each limit (the org's spend cap and every budget) that notify |
forecast |
boolean | true |
notify when the forecast says a limit will be passed |
anomalies |
boolean | true |
detect spend anomalies |
anomaly_min_usd |
number | 10 | ignore anomalies smaller than this |
anomaly_sensitivity |
string | medium |
low, medium or high |
Notifications also go to org webhooks subscribed to spend.threshold, spend.forecast or spend.anomaly.
Spend anomalies
An anomaly is an hour whose spend is far above the usual hour for the org. Anomalies appear in the spend alert feed; open one for its evidence:
| Route | Permission | What it returns |
|---|---|---|
GET /api/admin/v1/spend-anomalies/{id} |
usage:read |
The 48-hour series against the usual hour, the top keys, the top requests (only with logs:read), and the keys it names with their pause state now |
A paused key answers 403 key_paused until someone with keys:write or billing:manage resumes it (the key
routes are on Admin API: orgs, members and keys).
Spend forecast
| Route | Permission | What it returns |
|---|---|---|
GET /api/admin/v1/spend-forecast |
usage:read |
?period=month|day (default month). The forecast to the end of the UTC month or day, with an 80 % range; for a month, against the org's spend cap and when it crosses it. Each budget's forecast in short |
The forecast reads the last 8 weeks of settled daily spend.
Savings
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/savings |
usage:read |
?days=7|14|30 (default 30; anything else 400). The savings plan from your own request log: cheaper service tiers per gear role, cheaper modes and commitment pricing, each with its math |
POST /api/admin/v1/savings/apply |
org:manage |
{gear, role, tier, monthly_usd?}: set one gear role's service tier (flex, batch, …, or null to remove it) through the gears' own save. Audited gears.updated and savings.applied |
PUT /api/admin/v1/savings/commitments |
billing:manage or org:manage |
{commitments: [...] | null}: your commitment price inputs; null restores the defaults. Audited |
Key group savings
| Route | Permission | What it returns |
|---|---|---|
GET /api/admin/v1/team-savings |
usage:read |
?month=YYYY-MM (default this month; one of the months listed in the answer). What each key group saved from the prompt cache, batch and flex tiers, local models, request dedup, cheapest routing and venom-auto, with trends and tips. Key groups only, never a person. A vak_ key sees its own key group |
Chargeback statements
A statement says what each key group, project, gear, key or member spent over a range, by model and by member, and what the prompt cache saved. It reads the same request rows billing meters, and flags spend booked without a log row.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/chargeback |
usage:read (a vak_ key: its own key group) |
One statement. Range: ?period=last_month|this_month|YYYY-MM or ?from=&to= (UTC days). ?group=team|project|gear|key|member. ?format=csv downloads it (audited chargeback.exported) |
GET /api/admin/v1/chargeback/schedule |
usage:read |
The monthly statement by webhook: {enabled, group_by, sent_month}. Off by default, group_by team (by key group) |
PUT /api/admin/v1/chargeback/schedule |
billing:manage or org:manage |
{enabled?, group_by?}. When on, the cron sends last month's statement once as the chargeback.statement webhook event. Audited chargeback_schedule.updated |
A project is the request's x-venom-project header, else the project its key had when the request was made.
Invoice reconciliation
Upload a provider's usage or cost export and compare it, per UTC day and model, with what Venom booked through your org's key for that provider. Only parsed rows are kept, never the file, and never prompt content.
| Route | Permission | What it does |
|---|---|---|
GET /api/admin/v1/reconciliations |
usage:read |
Past reconciliations, newest first, with totals |
POST /api/admin/v1/reconciliations |
providers:write |
Read, compare and keep one; audited |
GET /api/admin/v1/reconciliations/{id} |
usage:read |
One reconciliation compared now (today's prices for the suggestions) |
PATCH /api/admin/v1/reconciliations/{id} |
providers:write |
{threshold_pct?, recompute?}; recompute: true reads Venom's side again |
DELETE /api/admin/v1/reconciliations/{id} |
providers:write |
Remove it; audited. Another org's id answers 404 |
Body of POST:
| Field | Type | Default | Rule |
|---|---|---|---|
provider |
string | required | the provider the export is from |
credential_id |
string | every key the org has for the provider | narrow Venom's side to one provider key |
from, to |
string | required | the period, UTC days |
threshold_pct |
number | 5 | above 0, at most 100: a day and model whose difference passes it is flagged |
files |
array | one of files or rows |
[{name, csv, mapping?}]: the export as CSV text |
rows |
array | rows already parsed (the console parses in the browser) | |
format |
string | detected | openai, anthropic or generic |
export_key, file_names |
string, string[] | none | labels kept with the result |
curl -s "$VENOM_CLOUD/api/admin/v1/reconciliations" -H "$ADMIN" -H "Content-Type: application/json" \
-d "$(jq -n --rawfile csv openai-usage.csv \
'{provider: "openai", from: "2026-10-01", to: "2026-10-31", files: [{name: "openai-usage.csv", csv: $csv}]}')"Errors
| Status | code |
When |
|---|---|---|
| 400 | invalid_request |
a field out of range, an unknown field, days not one of the allowed windows, a downgrade budget without downgrade_model |
| 403 | forbidden |
the role lacks the permission (the message names it), or the target is another org |
| 404 | not_found |
an id from another org, or none |
| 409 | conflict |
a second budget for the same subject and period |
Related
- Venom Cloud APIs overview: credentials, roles, headers
- Admin API: daemons, fleet and reliability
- Admin API: customers and MSP: budgets and invoices for the customers you resell to
- Keys, budgets and limits on the orchestrator: the self-hosted equivalent