Skip to main content

Budgets

/budgets is the central place to create, enforce and monitor budgets across the platform. Select Budgets under Cost management in the sidebar.

Concepts: Budget hierarchy.

Who sees what​

  • Platform admins (ADMIN) see every section. They create, edit, pause and delete budgets, grant increases and manage alerts. ADMIN_VIEWER sees the same data read-only.
  • Everyone else, including team and org admins, sees the totals, Key budgets for their own keys, and increases on their own keys. Managed budgets and Alert thresholds are not shown. The Budgets gauge on the Dashboard can show a managed budget you own.

For platform admins, the organization switcher narrows Key budgets and the organization, team, application, key and agent choices in the budget form.

Totals​

Four tiles: Tracked keys (and how many have a budget limit), Total spend (against the sum of effective key budgets), Near limit (keys at 80% or more) and Active increases.

Managed budgets (platform admin)​

A managed budget covers one scope: an organization, team, application, virtual key, user, tag, customer, cost center, agent or tool. Each budget records:

  • accountable owner and optional cost center
  • USD amount, grace amount and start/end dates
  • daily, weekly, monthly, quarterly, yearly, custom-day or one-time period
  • monitor, warn, block or require-approval enforcement
  • optional unused-budget rollover
  • a status: Draft, Active, Paused or Archived
  • up to 20 thresholds, each with an action

For cost-center enforcement, choose Cost center as the scope and select the managed cost center as the scope value. The separate optional Cost center field is accounting metadata on a budget; setting it on a team- or key-scoped budget does not turn that budget into a cost-center-scoped limit.

Create and assign managed cost centers from Cost centers (Manage cost centers). They are distinct from tags.

Each budget is a row showing:

  • name, status, scope, owner and cost center
  • Period, with the next reset, start or end date
  • spend against amount, with a marker for each threshold (legend: Notify, Approval, Block)
  • Forecast: when the money runs out at this period's average daily spend, for example Runs out ~Oct 21 · 9 days before reset, On track · ~72% at reset, Exhausted or Not enough data yet. Only active budgets are forecast.
  • Controls: enforcement and thresholds
  • Edit, Pause / Activate, and a delete button

The Scope filter narrows the list to one scope type as soon as you pick it.

BLOCK rejects new gateway calls with 429 budget_exceeded. MONITOR and WARN continue serving requests while recording and notifying. An exhausted REQUIRE_APPROVAL budget returns budget_approval_required and opens an approval request.

Create or edit a budget​

Create budget in the page header opens a form in five sections:

  1. Identity: Name, Description, Owner and Cost center.
  2. Scope: what the budget covers, then the specific target. Scope types with nothing to target yet are disabled.
  3. Amount and period: Amount (USD), Period, Starts, Ends (required for one-time budgets), Grace amount and Roll over unused amount.
  4. Enforcement: Monitor only, Warn, Block at limit or Require approval, plus Status.
  5. Thresholds: Add threshold adds a row with a percentage, an action (Notify, Block or Approval) and optional emails. Percentages must be unique.

New budgets start as monthly, Block at limit and Active, with thresholds at 70% (Notify), 90% (Notify) and 100% (Block).

The Summary beside the form updates as you type. It shows the amount and period, a bar with each threshold, and a What happens list with the dollar amount at which each threshold acts. When you edit a budget, it also shows this period's spend and forecast.

Edit opens the same form with Save changes. Delete a budget from the row or with Delete budget in the edit form. Deleting asks for confirmation and removes the budget's threshold history.

Key budgets​

Spend against each key's own budget, including temporary increases. Columns: Key / Team, Current spend, Budget usage, Effective budget, Reset and Status. Status is Near limit at 80% and Blocked at 100% or when the key is blocked.

Search keys or teams, and filter by status or team. Platform admins see active, blocked and pending-reveal keys; everyone else sees their own.

Temporary increases​

A temporary increase adds to a key's effective budget until it expires on its own. Temporary increases lists the active ones with amount, expiry, who granted them, the reason and days left. Everyone sees increases on their own keys.

Platform admins select Grant increase in that section, in the Key budgets toolbar, or on a key's row (which preselects the key). The dialog has:

  • Key, with this period's spend and current effective budget
  • Amount (USD), with quick picks of +$500, +$1,000, +$2,000 and +$5,000
  • Duration: 1, 7, 14 or 30 days, or any value from 1 to 365
  • Reason (optional)
  • the effective budget now and after the increase

Alert thresholds (platform admin)​

Thresholds on managed budgets are the main way to alert on spend. The Alert thresholds section holds the older key, team and tag alert rules, which the gateway still checks during the migration. Add alert still creates one:

  • Watch a Key, Team or Tag, then choose which one
  • Threshold: 1–100% of its budget, with quick picks of 50%, 75%, 80% and 90%
  • Extra emails (optional, comma-separated)
  • a preview of this period's spend and the amount at which the alert fires

Each row shows the percentage, subject, extra emails and when it last fired. Removing an alert asks for confirmation (Remove alert).