Daily and yearly ceilings
Cap what the organisation, a team or a key can spend in one day or one year, on a calendar in your own time zone and fiscal year.
A monthly budget caps a calendar month. A daily or yearly ceiling caps a shorter or a longer stretch of the calendar: "no more than $200 a day for this team", or "no more than $50,000 in our fiscal year for the whole organisation". Each one resets at a time you can name: local midnight for a day, the first day of your fiscal year for a year.
Preview. While daily and yearly ceilings are in preview, they do not refuse requests and no alert is sent. Nothing is limited until you add a ceiling, and no ceiling is set by default.
What a window is
A window is the stretch of time a ceiling counts spend over. Every request's cost lands in exactly one window of each kind, and when a window ends the next one starts from zero.
| Window | Starts | Ends | Named |
|---|---|---|---|
| Day | Midnight in your budget time zone | The next midnight | By its date, for example 2026-10-06 |
| Year | Midnight on the 1st of your fiscal start month | The same date a year later | By the year it starts in, for example FY2026 |
A fiscal year is named for the calendar year it starts in. If your fiscal
year starts in April, the year that begins on 1 April 2026 is FY2026 and runs
to the end of 31 March 2027. With the default start month, January, a year is
the calendar year.
A day on which the clocks change is still one day: it is 23 or 25 hours long, and it still runs from midnight to midnight.
Monthly budgets are unchanged
Monthly budgets, and the Default cap per virtual key, stay as they are. They are set on the Organization, Teams, Members, Customers and Keys tabs, and they follow the UTC calendar month: they reset at 00:00 UTC on the 1st, whatever time zone you choose below. Daily and yearly ceilings sit alongside them. A request has to have room in every ceiling and budget that covers it.
A ceiling
A ceiling applies to one scope over one period:
- Scope: the whole organisation, one team (every key assigned to it), or one key (a single proxy key).
- Period: Daily or Yearly.
- Ceiling: an amount in US dollars. You choose it; nothing is filled in for you.
- Action: what happens when spend in the window reaches the ceiling.
| Action | What it does |
|---|---|
| Alert only | You are notified when spend in the window reaches the ceiling. Requests are not refused. |
| Block requests | Requests the ceiling covers are refused until the window resets. |
Downgrade model is not offered for daily and yearly ceilings. Each scope can have one daily and one yearly ceiling, and an organisation can have up to 50 daily and yearly ceilings in all.
What is counted
Ceilings are in US dollars and count spend the same way budgets do: CoreValue reserves the worst-case cost of a request before it runs, then corrects to the actual cost when it finishes. Spend on your own provider keys counts, as it does for monthly budgets.
A request that would take spend in a window past a Block requests ceiling is the one that is stopped; a window that reaches exactly the ceiling is still served. An Alert only ceiling is checked against spend from requests that have finished, so its alert can come shortly after the ceiling is passed.
A ceiling added partway through a window counts the spend already in it. A $50 daily ceiling added in the afternoon of a day that has already spent $80 is over at once.
The budget calendar
Your organisation's budget calendar is a time zone and the month your fiscal year starts in. It decides where every daily and yearly window begins and ends. Until you set it, it is UTC with a fiscal year starting in January.
- Time zone: an IANA name, for example
UTC,Asia/KolkataorAmerica/Los_Angeles. - Fiscal year starts in: any month, January to December.
A change applies at once, not at the next boundary: today and this year are redrawn the moment you save. Because that can put a ceiling over its limit with no new spend, the console shows, before you save, each enabled ceiling's spend in its window now and in the window the new calendar would give it. Every change is recorded in the audit log.
What the calendar does not move
The calendar moves the daily and yearly ceilings' windows and nothing else.
- Monthly budgets stay on the UTC calendar month.
- Chargeback stays on UTC calendar months, and a closed month never changes: a month you have closed keeps the figures it was closed with, whatever you later set here.
- The month-end forecast and margin alerts stay on UTC calendar months.
Set a ceiling
- Open Budgets & Limits → Windows.
- Press Add ceiling.
- Choose the scope (and the team or key), the period, the ceiling in dollars and the action.
- Press Save ceiling.
Each row shows the ceiling's current window and when it resets, in your budget time zone. You can switch a ceiling off without deleting it, edit its amount or action, or delete it. The scope and period cannot be changed on an existing ceiling; add a new one instead. A change reaches the gateway within about two minutes.
To set the calendar, use the Budget calendar section on the same tab, check the preview, and press Save calendar.
Anyone in the organisation can see the ceilings and the calendar; adding, editing, switching and deleting ceilings, and changing the calendar, need permission to manage spend controls.
Plans
Daily and yearly ceilings are included in the Growth and Enterprise plans. A time zone other than UTC, or a fiscal year that does not start in January, is included in Enterprise. If your plan changes, the ceilings and the calendar you already set keep working; you cannot add or change them, but you can still delete a ceiling and return the calendar to UTC and January.
When a request is blocked
With Block requests and enforcement on, a refused request gets HTTP 429
in your provider's own error format, as a monthly budget refusal does. The
message names the ceiling, for example Team daily budget of $200.00 exceeded,
and a Retry-After header says how many seconds remain until the window
resets. The ceiling clears by itself when the next window starts; nobody needs
to reset it.
When a request is covered by several ceilings, the key's is checked first, then
the team's, then the organisation's, and a daily ceiling before a yearly one.
The first that has no room refuses the request. It is recorded with the rule
budget_window:<scope>:<period>, for example budget_window:team:day.
If CoreValue cannot check
Ceilings fail open: if they cannot be read or a window's spend cannot be
counted, the request is served and CoreValue logs why. The one exception is an
organisation whose budget fail mode is set to fail closed; a Block requests
ceiling whose spend could not be counted refuses the request with 503.
Alerts
While ceilings are in preview, no alert is sent. Once enforcement is on, an organisation or team ceiling that is reached sends a breach alert to your budget alert recipients by email. The alert says "daily" or "yearly" in place of "monthly". Webhook delivery of budget alerts is not available yet; webhooks carry request logs only. A ceiling that keeps being reached sends at most one alert an hour, not one per request. A key's ceiling records the breach but sends no alert, as a key cap does.
Daily ceilings and velocity limits
A daily ceiling and a velocity limit both cap spend over a stretch of time, and they answer different questions.
| Daily ceiling | Velocity limit | |
|---|---|---|
| The window | A calendar day, midnight to midnight in your budget time zone | A rolling window, 1 minute to 1 day, that always covers the most recent stretch of time |
| Resets | At midnight | Never all at once; old spend slides out of the window |
| Answers | "How much did we spend today?", against a figure you can show as "$X of $Y today" | "Is something spending too fast right now?", to catch a runaway loop in minutes |
| Applies to | The organisation, a team or a key | A key |
| Your own provider keys | Counted, and can be blocked | Counted, but only alert |
Use both if you need both: a velocity limit to stop a loop quickly, and a daily ceiling for a daily allowance.
What is not included yet
- Daily and yearly ceilings for a member or a customer. Today a ceiling applies to the organisation, a team or a key.
- Downgrade model as an action.
- Early warnings (for example at 80%) before a daily or yearly ceiling is reached.