---
title: "Admin API: usage, budgets and spend"
description: 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.
section: cloud
order: 320
audience: [builder, operator, agent]
sources: [services/nodejs-cloud/app/api/admin/v1/usage, services/nodejs-cloud/app/api/admin/v1/budgets, services/nodejs-cloud/app/api/admin/v1/spend-alerts, services/nodejs-cloud/app/api/admin/v1/spend-anomalies, services/nodejs-cloud/app/api/admin/v1/spend-forecast, services/nodejs-cloud/app/api/admin/v1/savings, services/nodejs-cloud/app/api/admin/v1/team-savings, services/nodejs-cloud/app/api/admin/v1/chargeback, services/nodejs-cloud/app/api/admin/v1/reconciliations, services/nodejs-cloud/lib/budget, services/nodejs-cloud/lib/chargeback, services/nodejs-cloud/lib/savings, services/nodejs-cloud/lib/reconcile, docs/cloud-mesh.md]
features: [cloud.api-admin-usage, cloud.api-admin-budgets, cloud.api-admin-spend-alerts, cloud.api-admin-spend-anomalies, cloud.api-admin-spend-forecast, cloud.api-admin-savings, cloud.api-admin-team-savings, cloud.api-admin-chargeback, cloud.api-admin-reconciliations]
---

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](/docs/cloud/api-overview.md#admin-credentials)). 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](/docs/cloud/api-overview.md#errors).
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 {#first-call}

```bash
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"
}'
```

```ts
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());
```

```python
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 {#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) {#budgets}

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](/docs/cloud/api-overview.md#limits).

| 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 {#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 {#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](/docs/cloud/api-admin-access.md#keys)).

## Spend forecast {#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 {#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 {#team-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 {#chargeback}

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

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 |

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

- [Venom Cloud APIs overview](/docs/cloud/api-overview.md): credentials, roles, headers
- [Admin API: daemons, fleet and reliability](/docs/cloud/api-admin-fleet.md)
- [Admin API: customers and MSP](/docs/cloud/api-admin-msp.md): budgets and invoices for the customers you resell to
- [Keys, budgets and limits on the orchestrator](/docs/orchestrator/keys-and-budgets.md): the self-hosted equivalent
