Budgets

Budgets let you set spending and usage limits at multiple levels of your organization hierarchy. Each budget defines per-period limits and an enforcement action — warn (log and surface warnings) or block (reject further requests for that scope).

Budget List

The Budgets page displays a paginated table with these columns:

Column	Description
Scope	The scope type and ID (e.g. “organization / Acme Corp”).
Limits	The configured cost / token / request limits.
Current Usage	A progress bar showing consumption against the limit.
Action	`warn` or `block` — what happens when a limit is reached.
Status	`Active` or `Disabled`, reflecting the budget’s `enabled` flag.

Creating a Budget

Click Create Budget to open the form.

Scope

Budgets can be scoped to any level in the multi-tenancy hierarchy. Select the Scope Type and the specific Scope ID it applies to:

Scope Type	Value	Description
Deployment	`tenant`	Applies to the whole deployment and every user in it. The stored value is `tenant`.
Organization	`organization`	Applies to one organization and everything beneath it.
Department	`department`	Applies to a department within an organization.
User	`user`	Applies to a single user.
API Key	`apiKey`	Applies to a specific API key.

Limits

Set one or more of the following limits. All are optional — configure only the ones relevant to your use case. The period each limit covers is encoded in the field name:

Limit	Description
`dailyUsd`	Maximum dollar spend per day.
`weeklyUsd`	Maximum dollar spend per week.
`monthlyUsd`	Maximum dollar spend per month.
`dailyTokens`	Maximum total tokens (input + output) per day.
`monthlyTokens`	Maximum total tokens per month.
`dailyRequests`	Maximum number of requests per day.

There is no separate “period” selector — daily/weekly/monthly cadence is implied by the limit you set, and usage counters reset on their natural daily/weekly/monthly boundaries (UTC).

Alerts

Add one or more alert rows to be notified before a hard limit is hit. Each alert has:

Field	Description
Threshold	Percentage of a limit (1–100) at which the alert fires.
Type	`warning` or `critical`.
Notify Via	One or more channels: `email`, `webhook`, `slack`, `in-app`.

Action

The Action field controls enforcement when a limit is reached:

warn — requests are allowed through; a warning is logged and attached to the response.
block — requests for the scope are rejected.

Enabled

The Enabled toggle activates or pauses the budget without deleting it.

Automatic Enforcement

When a budget with action: block reaches a limit, the gateway rejects further requests for that scope with a 429 Too Many Requests carrying the BUDGET_EXCEEDED error code. Budgets with action: warn allow the request and attach warning information to the response instead.

Enforcement is hierarchical — if the deployment-level budget blocks, every organization, department and user beneath it is blocked, regardless of their individual budget state. Budget checks fail closed: if the budget service errors, the request is blocked for safety.

Budget Alerts

When an alert threshold is crossed, the gateway delivers the alert over the channels listed in that alert’s Notify Via (notifyVia) set. Each alert fires exactly once — dispatch is atomically deduplicated, so concurrent requests that all cross the same threshold produce a single notification.

Three external delivery channels are supported, each gated on environment configuration and delivered best-effort in isolation: a channel that is unconfigured is a silent no-op, and one channel failing (or being unset) never blocks the others.

Channel (`notifyVia`)	Delivery	Required environment
`email`	Email via SMTP (nodemailer). No-op unless SMTP is configured and the budget scope has email recipients.	`SMTP_HOST` (plus `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`, `SMTP_PASS`, `SMTP_FROM`)
`webhook`	HTTP `POST` of a `budget.alert` JSON payload. When a secret is set, the request carries an HMAC signature in the `X-Webhook-Signature` header.	`BUDGET_ALERT_WEBHOOK_URL` (and `BUDGET_ALERT_WEBHOOK_SECRET` to sign)
`slack`	Message posted to a Slack incoming webhook.	`SLACK_WEBHOOK_URL`

The in-app channel is surfaced within the dashboard and involves no external delivery.

The alert message identifies the scope, the percentage of the limit reached, the current-versus-limit values, the limit type, and the configured threshold. See the Environment Variables page for the exact keys and their formats.

Editing and Deleting Budgets

Click Edit to modify limits, alerts, action, or the enabled flag. The scope and scope ID cannot be changed after creation — delete and recreate the budget to re-scope it.
Click Delete to remove a budget. A confirmation dialog warns that usage tracking for that scope will stop. Deletion does not affect historical usage data.

Best Practices

Set deployment-level budgets as overall spending caps, then use department or user budgets for finer-grained control.
Use warn action with alerts during rollout to observe spend before switching to block.
Add an alert at ~80% so teams can react before hitting a hard block limit.
Combine cost limits with token limits for defense in depth — a low-cost model can still consume excessive tokens.