Budgets & alerts

Per-key monthly USD caps with soft-alert thresholds and projected-overrun alerts — keep RouteShift LLM spend predictable and stop runaway agents cold.

Every virtual key can carry a monthly USD budget. RouteShift enforces it server-side: a soft threshold fires a notification, the hard cap blocks new requests until the next monthly reset, and a projected-overrun model alerts you before either trips.

Rendering diagram…

Budget lifecycle: spend accumulates in microcents, a soft threshold fires notifications while traffic continues, the hard cap blocks new requests with a 429, and the monthly reset restores the key to full capacity.

Budget mechanics

Budgets are stored in microcents (1/10,000th of a cent) so even fractional-cent calls aggregate cleanly. Each request decrements the running monthly total atomically; on the first day of each calendar month (UTC) the running total resets to zero.

For a key with a $50 monthly budget and an 80% soft-alert threshold:

State	Behavior
0–80% used	Normal traffic. No alerts.
80–100% used	Soft alert fires once per threshold crossing (email, Slack, or webhook). Traffic continues.
100% used	Hard cap. New requests return `429` with `X-RouteShift-Reason: budget_exceeded`. In-flight requests finish.
Reset	At 00:00 UTC on day 1, the running total drops to zero and the key resumes serving.

Setting a budget

Open key settings

Navigate to Settings → Keys and click the key you want to cap. Each key shows its current month-to-date spend and remaining budget inline.

Set the monthly cap

Enter a USD amount in the Monthly budget field. The value is stored internally in microcents, so $50.00 becomes 500,000,000 microcents — you never need to think about the internal representation.

Configure the soft threshold

Set the alert threshold as a percentage (default: 80%). When spend crosses this line, RouteShift fires a notification to every configured channel. The alert fires once per crossing — it won't spam you on every request after the threshold.

Choose alert channels

At Settings → Notifications, configure where budget alerts go: email, Slack incoming webhook, or a generic JSON webhook. You can enable all three simultaneously.

Projected-overrun alerts

In addition to the hard/soft thresholds, RouteShift fits a linear trend to the trailing 7 days of spend and projects month-end usage. If the projection exceeds the budget — even though current usage is still under the soft threshold — a projected overrun alert fires once per key per month. This catches sudden ramps before they hit the cap.

The projection is shown on the Billing → Budgets page as a dotted forecast line over the actual spend curve.

How the projection works

The model is intentionally simple — a least-squares linear fit on the trailing 7 days of daily spend, extrapolated to the last day of the current month. It's not a time-series forecast; it's a "if this trend continues, where do we land?" sanity check.

Scenario	Projection behavior
Steady daily spend	Projects linearly; accurate for stable workloads
Sudden ramp (new agent deployed)	Catches the ramp within 2–3 days of data
One-time spike (backfill job)	May over-project; the alert fires once and won't repeat unless the trend sustains
Mid-month budget increase	Projection recalculates against the new budget on the next daily rollup

Multi-tier alerts

Configure where alerts go at Settings → Notifications:

Email — to the workspace owner and any address on a mailing list.
Slack — via incoming webhook; the alert message includes the key name, percent used, and a deep link to the billing page.
Webhook — POST application/json payload with { key_id, threshold, used_microcents, budget_microcents, period }. Useful for routing into an oncall system.

Webhook payload

{
  "key_id": "vk_a1b2c3d4",
  "key_name": "production-agent",
  "alert_type": "soft_threshold",
  "threshold_pct": 80,
  "used_microcents": 4000000000,
  "budget_microcents": 5000000000,
  "period": "2026-07",
  "projected_month_end_microcents": 6200000000,
  "dashboard_url": "https://app.routeshift.io/billing/budgets?key=vk_a1b2c3d4"
}

The alert_type field is one of soft_threshold, hard_cap, or projected_overrun. The projected_month_end_microcents field is included on all alert types so your oncall system can distinguish "we're at 80%" from "we're at 80% and trending to 124%".

Workspace-wide rollups

Beyond per-key budgets, the Billing → Spend view shows total workspace spend with the same projected-overrun model applied at the org level. Use it to set a rough business cap separate from per-key safety nets.

Budgets are a safety net, not a forecasting tool. For accurate forecasts, pair budgets with the Optimize page to remove waste before it shows up in the trend line.

On this page