Budgets and alerts
odnoga enforces spend ceilings at two levels. Both are checked on every request and the stricter one wins.
1. Workspace budget
Workspace → Budget. One active budget per workspace.
| Field | Notes |
|---|---|
| Period | day or month (UTC). |
| Cap (USD) | Hard ceiling for that one workspace. 0 = unlimited. |
| Warn at (%) | Threshold that fires the budget_80-style alert (default 80). |
| Hard stop | When on, 100% returns 402 budget_exhausted. When off, you only get alerts. |
Seeded automatically at signup with a $25 monthly cap as a safety net — edit any time, or set to 0 to remove the limit.
2. Tenant spend cap (global)
Tenant admin → Spend cap. One global ceiling shared by every workspace in the tenant.
| Field | Notes |
|---|---|
| Period | day or month (UTC). |
| Cap (USD) | Sum of cost_usd across all workspaces in the tenant. 0 = unlimited (default). |
| Warn at (%) | Reserved for tenant-level alerting. |
| Hard stop | When on and the cap is reached, all workspaces in the tenant return 402 budget_exhausted with reason Tenant budget exhausted. |
Only tenant admins (or super admins) can view or edit it. Use this when you want a single master ceiling regardless of how many workspaces a team spins up.
At 80% and 100% of the workspace cap odnoga enqueues budget_80 / budget_100 events. Configure subscriptions to ship them via email.
Alerts
Workspace → Alerts → Subscribe.
| Kind | Fires when |
|---|---|
budget_80 | Spend crosses 80% of the budget cap. |
budget_100 | Spend crosses 100%. |
error_rate | Rolling 5-min error rate > threshold. |
latency_p95 | P95 latency > threshold for N minutes. |
key_rotated | A virtual or vault key was rotated. |
key_revoked | An API key was revoked. |
Delivery is by email and is fire-and-forget; a failed send is recorded with its error and shown in the alert history.
Reset windows
When your workspace or organisation has a budget window, responses carry x-ratelimit-reset: the unix-seconds timestamp when that window rolls over. Without a budget window (prepaid credit only) the header is absent — don't rely on it being there. It tells you when budget refills, not when to retry a 429; for that, honour Retry-After.
Recommended setup
- Tenant spend cap: monthly ceiling matching your finance-approved budget, hard stop on.
- Workspace budget: per-workspace monthly cap, hard stop on.
- Subscriptions:
budget_80,budget_100,error_rate. - Allowed models: only what your team is approved to use.