Budget configuration
Set up budgets that stop overspend without stopping your product: which layers to use, which action to pick, and how to tighten them once you have real numbers.
This guide takes you from no budgets to budgets you can rely on. It uses the controls on Budgets & Limits; the page-by-page reference is Budgets.
How the layers fit together
A request is checked against every budget that covers it, and the first one that is full decides what happens.
| Layer | Caps | Use it for |
|---|---|---|
| Organisation | All spend | A backstop for the month. |
| Team | Every key assigned to the team | Each team's share, and chargeback. |
| Member | Every key a member owns | People with their own keys, such as developers using coding assistants. |
| Customer | Requests carrying that Cova-Customer-Id | Your own customers. See Per-customer budgets. |
| Key | One CoreValue key | A single service or environment. |
All of them are monthly and reset on the 1st (UTC). Spend already made this month counts as soon as you set one.
Choose what happens at the budget
| Action | What it does | Pick it when |
|---|---|---|
| Alert only | Serves the request and records the breach. Alert recipients are emailed when an organisation or team budget acts. | You are learning what normal looks like. |
| Downgrade model | Rewrites the request to a cheaper model from your downgrade mappings, then serves it. Organisation and team budgets only. | Running on a cheaper model is better than stopping. |
| Block requests | Refuses with HTTP 429 before the provider is called. | The cap is a hard limit. |
Member and customer budgets stop spend only with Refuse the request. Block and Downgrade need the Growth plan or higher; Alert only works on every plan.
A setup that works
Give each service and environment its own key
Create a key per service, and separate keys for production, staging and development, on Governance → Keys. Spend can then be capped and read per key, and a test loop in staging cannot use production's budget.
Set an organisation budget on Alert only
On Budgets & Limits → Organization, set a Monthly Budget above what you expect to spend, with Action When Budget Exceeded on Alert only. The Month-End Forecast on the same tab shows where the month is heading.
Get warned early
On Notifications → Budget alerts, add the people who should hear about it
and set Warn before the budget is reached, for example 80%, 95%.
Cap the keys that can run away
On Budgets & Limits → Keys, click Edit caps on each service key and add
a Cost limit for the month. Add a Count limit too, for example
1,000 requests per 1 hour, on keys used by agents or batch jobs. A key over
either limit gets 429 while every other key carries on.
To cap every key at once, set Default cap per virtual key on the Organization tab. A key's own cap always wins.
Add team budgets
On Budgets & Limits → Teams, give each team a Monthly budget, and assign keys to teams on the Keys tab. See Team chargeback.
Watch a week, then tighten
After a week, open Budgets & Limits → Actions to see what each budget would have done. When the numbers match what you expect, lower the budgets to what you can afford and switch the ones that matter to Block requests, or to Downgrade model with a mapping for every model you use.
Stop a runaway loop
A monthly budget catches overspend at the end of the month; a loop can spend a lot in an hour. Three controls catch it sooner:
- A Count limit on the key, as above, refuses once the key makes too many requests in a window.
- Rate limits cap requests or cents per window for the whole organisation, per user or per tag.
- Velocity limits and daily ceilings cap spend per minute, hour or day. Both are in preview: they record what they would have refused but do not refuse yet.
Things to know
- Requests already in flight when a budget fills still complete, so spend can land slightly above it.
- A budget change takes effect within about a minute.
- If CoreValue cannot read a budget, the request is served: budgets never take your traffic down.
- Changing budgets needs the Owner or Admin role.
Related
- Budgets: every field on every tab.
- Budget alerts
- Per-customer budgets
- Errors: what a refused request looks like.