Skip to content
Docs menu

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.

View .md

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