Skip to content
Cloud Score Docs

Set budgets and get alerted

Tag spend to a team, cap it with a warning workspace budget and a blocking team budget, then wire a signed webhook and two threshold rules so you hear about it before the block lands.

WhereAnalyticsBudgetsNeeds an API key with trafficNeeds a public webhook URLOpen in Cloud Score
The Budgets tab: Manage organization limits, the 1-month budget, Spend this period, Remaining and Forecast end of period tiles, the Organization Budget Utilization meters, then Daily Spend vs Even-burn Pace beside Spend by Provider.
Budgets: the organization's limits for the current period, spend and the forecast against them, the daily pace, and spend by provider.
On this page

The path

API keystag the key
Budgetscap the spend
Alert channelswhere to notify
Threshold ruleswhen to notify
Blocked requestwhat clients see
Forecastwatch the period

A budget caps monthly model spend at one scope and either warns or blocks at 100 %. A threshold rule watches the same numbers every 5 minutes and delivers to a channel. This guide sets up a workspace budget that warns, a team budget that blocks, one signed webhook, and two rules: one on budget utilization, one on spend.

Budgets count model spend at list price only. Platform overhead (classifier and embedding calls) is subtracted from Saved (net) on Optimizations and never counted against a budget. See Costs, savings, and estimates for what list price means.

Make spend attributable

A team, application, agent, or environment budget only gates requests that carry that exact tag. Setting defaults on the API key makes every untagged request on it attributable, including its history.

  1. Click API keys under Admin in the sidebar.

    The key table opens. The Attribution column shows — for a key with no defaults.

  2. On the key's row, open the ⋯ menu and click Edit tags.

    The Attribution — {key name} dialog opens on the Cost attribution defaults (optional) block. Its helper reads Applied to requests on this key that carry no metadata or X-Dex-* tag of their own.

  3. Fill Team, Application, and Environment.

    For example support, helpdesk, production. Values are trimmed and capped at 120 characters. There is no field for agent or end user here.

  4. Click Save.

    The row now shows chips team=support, application=helpdesk, environment=production. On failure the dialog shows the server message or save failed.

How a request gets its attribution tags. A budget on the Team scope matches the resolved team value exactly.
Source of a tagPrecedenceNotes
Request body metadataHighestmetadata.team, metadata.application, metadata.agent, metadata.environment, metadata.end_user; the OpenAI-compatible user field maps to end_user.
Request headersMiddleX-Dex-Team, X-Dex-Application, X-Dex-Agent, X-Dex-Environment, X-Dex-End-User.
Key defaults (Edit tags)LowestTeam, application, environment. Untagged history inherits the key's current defaults; end_user never inherits.

Usage & cost shows what has no team.

On Usage & cost, Breakdown by Team keeps an Unassigned (no team) row for requests whose API key had no assigned team, and the reported-tag dimensions show Not reported for requests that carried no tag. See Attribution for the request-side tags.

Set the budgets

Every request is admitted against all the budgets that apply to it before a provider is called. The workspace budget below warns so nothing stops; the team budget blocks so one team cannot exhaust the month.

The Budgets tab: Manage organization limits, the 1-month budget, Spend this period, Remaining and Forecast end of period tiles, the Organization Budget Utilization meters, then Daily Spend vs Even-burn Pace beside Spend by Provider.
Budgets: the organization's limits for the current period, spend and the forecast against them, the daily pace, and spend by provider.

First, a workspace budget that warns.

  1. Click Budgets under Analytics in the sidebar.

    With no budgets the table reads No budgets yet — requests are not gated. Add one above. The basis line under the heading reads Basis: model spend (list price, the figure the gate reserves against). Platform overhead — classifier and embedding calls — is reported separately on the Overview and is not counted here.

  2. In New budget, set Scope to Workspace.

    The Value field is disabled and reads whole workspace.

  3. Enter Amount (USD / month), for example 1000.00.

    Leave Soft threshold (%) at 80 and At 100 % on warn. Add budget stays disabled until an amount is entered.

  4. Click Add budget.

    The button reads Saving…, the form resets, and the row shows Workspace / whole workspace, $1,000.00, 80%, badge warn, and — no spend recorded this period until traffic arrives.

Then, a team budget that blocks.

  1. Set Scope to Team and Team tag to support.

    The field's placeholder reads exact attribution value: it must match the team tag character for character.

  2. Enter 250.00 as the amount and choose block under At 100 %.

    The Block requests at 100 %? dialog opens. Read the consequence, then click Block at 100 %. A red block badge appears next to Add budget.

  3. Click Add budget.

    The row shows Team / support, $250.00, 80%, badge block, and a switch to warn link.

What the block dialog says.

Requests attributed to team "support" will be refused — HTTP 403 on the OpenAI-compatible endpoint, status: blocked on the native one — as soon as this month's model spend plus in-flight estimates exceed $250.00. Warn reports the same breach in X-Dex-Budget-State and serves the request. Clients see the block immediately; nothing is queued or retried.

The budgets table after both rows exist.
ColumnWhat it shows
ScopeScope label plus the value: whole workspace, a key as name and prefix, or the tag.
Amount / monthThe cap, as a money string.
Soft atThe percentage at which the breach is reported while the request is still served, for example 80%.
At 100 %Badge block or warn, with switch to warn / switch to block. Switching to block asks first.
This periodUsage bar: spent, utilization, in flight, and the period start; or — no spend recorded this period.
Enabledon / off. A disabled row dims to 60 %.

Before you delete or disable a budget.

Delete asks Delete this budget?and discards this period's recorded spend with the row. A budget switched off accumulates no usage, so any Budget utilization rule on it goes quiet. Budgets are monthly only. A blank Soft threshold (%) falls back to 80.

Add an alert channel

A channel is where firings go: a signed webhook or an email address. The rules in the next station deliver to it; without one they only record.

The Alerts tab of Budgets: Alert scope with its registered-agent and environment filters, then Threshold rules with the New threshold rule form above the rule list.
Alerts: scope what you see, then add a threshold rule. Deliveries, alert channels and recorded anomalies follow further down the tab.
  1. Click the Alerts tab.

    With no channels the Alert channels card reads No channels — anomalies are recorded but nothing is notified.

  2. Set Kind to Webhook (signed POST) and Name to ops pager.

    Paste your public HTTPS endpoint into URL. Leave Secret (webhook, optional — generated if blank) empty, or type at least 16 characters. Add channel stays disabled until name, target, and a valid secret are in place.

  3. Click Add channel.

    A panel reads Signing secret — shown once. Store it with the receiver now; it cannot be read back. Click Copy, store the value with your receiver, then click Done.

  4. Click Test on the channel row.

    The button reads Sending…, then a line under Status reads test ok with the HTTP code and latency, or test failedwith the error. The row's badge is enabled.

What the receiver should verify. Targets are stored masked and are never shown again in full.
Header on every webhook deliveryValue
X-Dex-Signaturesha256=HMAC(secret, body), computed with the signing secret.
X-Dex-TimestampWhen the delivery was signed.
X-Dex-Eventcost.rule for a threshold rule firing, cost.anomaly for the hourly anomaly detector.

Targets must be public.

Loopback, private, and cloud-metadata addresses are refused when saved and again on every delivery. A channel that keeps failing is disabled automatically; the row then shows {n} consecutive failures. Rotate secret breaks the receiver until you update it; the new value is shown once.

For email, choose Email (SMTP) and fill Address; the secret field is disabled. SMTP itself is not configured on this page.

Add threshold rules

Rules are evaluated every 5 minutes over a sliding window, fire at most once per window, then wait out their cooldown. The first rule warns before the team block lands; the second catches a spend spike anywhere in the workspace.

Rule one: fire when the support budget passes 90 % of its month.

  1. In Threshold rules, set Name to support budget 90 and Metric to Budget utilization.

    The hint reads spend + in-flight reservations against the budget for the current month.

  2. Set Budget to team: support · $250.00/month.

    Only enabled budgets are listed. With none, the select reads no enabled budgets — create one on the Budgets tab.

  3. Set Condition to above and the threshold to 90.

    The input carries a % suffix. Set Re-check window to 6 hours; its hint reads utilization is over the month; the window only spaces repeat firings. Set Cooldown to 24 hours.

  4. Under Channels, tick ops pager (webhook) and click Add rule.

    Name, threshold, and value reset; metric, scope, window, cooldown, and channels are kept for the next rule.

Rule two: fire when workspace spend passes $25 in any hour.

  1. Set Name to hourly spend and Metric to Spend.

    The hint reads list-price model spend over the window: the same figure the budget gate uses.

  2. Set Scope to whole workspace.

    Any other scope needs a Value, and it must match one exact value.

  3. Set Condition to above 25.00, Window to 1 hour, Cooldown to 1 hour.

    The threshold input carries a $ prefix for this metric.

  4. Tick ops pager (webhook) and click Add rule.

    The row's Condition cell reads Spend > $25.00 over 1 hour with cooldown 1 hour under it.

  5. Click Test on the row.

    The button reads Checking…, then the status line reads would fire or would not fire followed by the observed value and the window. A test never fires and records nothing.

Window options run from 5 minutes to 30 days; cooldown from none to 24 hours.
SettingMeaningDefault
WindowThe sliding period the metric is measured over. A rule fires at most once per window.1 hour
Re-check windowShown instead of Window for Budget utilization. Utilization is always over the month; this only spaces repeat firings.1 hour
CooldownThe minimum gap after a firing before the rule can fire again.1 hour

Validation and quiet rules.

The threshold must satisfy threshold must be a non-negative number (up to 6 decimals). A rule with no channels shows No channels yet — the rule will record firings without notifying. and its row reads — (records only). An observed value of — means no data in the window, whereas spend over an empty window is 0, so a Spend rule with below acts as a silence detector.

What a blocked request looks like

Once the support team's month spend plus in-flight estimates exceed $250.00, its requests are refused before any provider is called. Nothing is queued or retried.

WhereWhat a blocked request looks like
OpenAI-compatible endpointHTTP 403.
Native endpointstatus: blocked in the response.
Any endpoint, budget on warnThe request is served; the breach is reported in the X-Dex-Budget-State header.
Playground route boardThe Policy station reads blocked and Record ends on blocked.
Observability › RequestsThe row's Gateway status is blocked.
Observability › Gateway healthThe Blocked series of Request outcomes includes it for the selected period; the Requests evidence sheet gives the exact counts.
Usage & cost › Breakdown bySet the Status chip (under More) to blocked: each team's row counts its refused requests, and View requests → in its drawer lists them.
Admin › DeveloperDocuments the status as A routing policy or budget blocked the request before execution.

The support team hits its cap on the 19th

What you do

Nothing yet. The helpdesk sends its usual requests on the helpdesk-prod key, all tagged team=support.

What Cloud Score does

Reserves each request's estimate against the Team / support budget. At 90 % the support budget 90 rule fires and posts to ops pager. When spend plus reservations exceed $250.00, the next request is refused.

What you see

A sent row under Deliveries, a blocked row in Observability, and the budget row's This period bar at or above 100 %. Clicking switch to warn lets traffic through again immediately.

A key can carry its own cap too.

Monthly budget (USD, optional) in Create API keyis a separate per-key cap, shown in the key list's Budgetcolumn. With budget pre-flight enabled it feeds the budget service as the key-scope budget; otherwise a legacy gate blocks requests once the calendar month's spend has reached the cap, with the message monthly budget exhausted: spent $X of $Y. Sandbox keys never skip the budget gate.

Watch the forecast

The Budgets page projects where the period lands against the organization budget, so you can raise a cap before a block rather than after.

  1. Open Budgets and read the organization tiles.

    They read the budget, Spend this period, Remaining (red and negative when over) and Forecast end of period, which reads Above the budget when the projection passes the limit. Until enough of the period has passed it reads — with the reason, for example Available after 2 days of the period, or a quarter of it if shorter. Without an organization budget the budget tile reads No limit and No organization budget.

  2. Read Organization Budget Utilization.

    The meter reads the share used, for example 62% used, with the spend and any in-flight reservations against the limit, then the token and request limits.

  3. Read Daily Spend vs Even-burn Pace.

    The chart draws Spend per day against the Even-burn targetfor each UTC day of the budget's current period. Without an organization budget it reads Set an organization budget to see the pace.

  4. To raise the cap, click Manage organization limits.

The organization tiles, Organization Budget Utilization and Daily Spend vs Even-burn Pacefollow the budget's own period; the tab has no range control. The forecast is linear: spend so far divided by the days elapsed, times the days in the period. They read the organization (workspace) budget only.

What to check afterwards

WhereWhat to look for
Budgets › Alerts › DeliveriesSet Status to sent, pending, failed, or dead. Each row names the Channel, the Source (a rule with its name, metric, and threshold, or an anomaly), Attempts, Next / sent, and Last error. Empty reads No deliveries.
Threshold rules › EventsExpands a rule's firing history: Fired, Observed, Threshold, Window; or Never fired. The status cell also reads last fired with the time.
Alert channels rowBadge enabled, or disabled with after {n} consecutive failures and when. Click Enable after fixing the receiver.
Budgets › This periodSpent, utilization, and in-flight reservations per budget, with the period start.
ObservabilitySet the Status chip to blocked to list refused requests (/logs). Open a row to see the route board's Policy station read blocked.
Usage & cost › Breakdown byUnder More, set the Status chip to blocked and keep the dimension on Team to see who was refused.
Recorded anomaliesThe hourly detector's rows for the last 30 days, one per group per day; empty reads None recorded — the hourly detector found nothing above threshold.

Deliveries retry with backoff until dead. A failed row shows its next attempt under Next / sent; fix the receiver and wait, or Test the channel to confirm it answers. Deleting a rule removes its events and their deliveries; deleting a channel removes its deliveries but keeps anomalies.

Related