Budget controls — TokenID

Budget controls cap AI spend across five dimensions and fire tiered alerts as you approach the limit. Caps are currently advisory — you get warned, not blocked.

How it works

A nightly job rolls captured events into a per-org spend ledger. The budget endpoints read that ledger live and compare it against the limits you configure. Each configured alert_thresholds_pct value (e.g. 70%, 90%, 100%) fires once per scope per period — wired to your existing alerts channel.

Configure limits

1. Open [token.audit.id/app/budget](https://token.audit.id/app/budget). 2. Set the monthly and daily caps for your org. 3. Optionally add per-user, per-project, and per-key daily caps. 4. Pick alert thresholds — the defaults are **70 / 90 / 100 %**. 5. Click **Save**.

```bash curl -X PUT https://token.audit.id/api/v1/budget/limits/{org_id} \ -H "Authorization: Bearer td_live_xxxx" \ -H "Content-Type: application/json" \ -d '{ "monthly_budget_cents": 500000, "daily_budget_cents": 25000, "per_user_daily_cents": 2000, "per_project_daily_cents": 5000, "per_key_daily_cents": 1000, "alert_thresholds_pct": [70, 90, 100] }' ``` Requires the `admin` role. All money values are integers in cents — `500000` is $5,000.

Cap dimensions

Field	Scope	Example
`monthly_budget_cents`	Org total per fiscal month	`500000` — $5,000/mo
`daily_budget_cents`	Org total per UTC day	`25000` — $250/day
`per_user_daily_cents`	Each user, per day	`2000` — $20/user/day
`per_project_daily_cents`	Each project tag, per day	`5000` — $50/project/day
`per_key_daily_cents`	Each API key, per day	`1000` — $10/key/day
`alert_thresholds_pct`	Percentages that fire alerts	`[70, 90, 100]`

Any field left null disables that dimension.

Check status

GET/api/v1/budget/status/{org_id}

Returns running totals against every configured cap, the projected month-end spend (linear daily extrapolation from month-to-date), and which alert thresholds have already tripped.

{
  "organization_id": "org_01abc…",
  "period_start": "2026-05-01",
  "period_end": "2026-06-01",
  "limits": {
    "monthly_budget_cents": 500000,
    "daily_budget_cents": 25000,
    "per_user_daily_cents": 2000,
    "per_project_daily_cents": 5000,
    "per_key_daily_cents": 1000
  },
  "spend": {
    "month_to_date_cents": 362400,
    "day_to_date_cents": 18450,
    "projected_month_end_cents": 539800
  },
  "alert_thresholds_pct": [70, 90, 100],
  "thresholds_triggered": [
    {"scope": "monthly", "threshold_pct": 70}
  ],
  "soft_cap_only": true
}

Example

curl https://token.audit.id/api/v1/budget/status/{org_id} \
  -H "Authorization: Bearer td_live_xxxx"

Read current limits

GET/api/v1/budget/limits/{org_id}

Returns the configured cap values without the spend rollup — useful for surfacing the current config in your own tooling.

Caps are currently advisory: TokenID fires alerts as you approach and cross each threshold, but does not reject calls. Hard enforcement at the proxy — automatic rejection of calls that would exceed a cap — is in development. For pre-call rules that block today, see [Enforcement](/api-reference/enforcement).