Budgets

What a budget watches, how its spend and forecast are computed, when it alerts, and why a budget can guard nothing.

Last updated 18 November 2026View as Markdown

A budget is an amount in euro cents for a period (monthly, quarterly or annual), a scope, and the percentages of the amount at which it alerts. A budget never stops or pauses anything by itself; a budget with an action proposes stopping resources, and a person approves (see Let a budget propose stopping resources).

What a budget counts

Scope Counts
The whole organization Every usage record of the organization
A project The resources that live in the project, as they are moved in and out
A saved view The resources the saved view's tag query selects now; editing the view changes the budget
Resources with a tag Resources matching 1–10 tag clauses, all of which must match; a clause without values matches any value of the key

Over the API the scopes are organization, resourceProject, project (a saved view) and tags. A resource without the scope's tags is not counted: untagged is not the same as zero. Registry and Git storage is metered for the whole organization, not per resource, so only a budget for the whole organization counts it; the Budgets page says how much a narrower budget leaves out.

A budget can also count only some services (serviceFilter). Several budgets may cover the same resource; each is evaluated on its own.

Periods

Months, quarters and years start at midnight German time on the 1st, the same moment as the invoice's billing period. Spend is summed from the usage records of the current period.

When a budget alerts

Once an hour, at five minutes past, every budget is evaluated. For each threshold the spend has reached, an alert is recorded once per period: it never fires again for that threshold in that period, even after you change the amount, and the next period starts clean. The alert records the spend, the amount and what the scope selected at that moment.

A monthly budget can also alert on its forecast (forecastThresholds): spend so far, plus what is billing now at its current rate for the rest of the month, plus usage-based charges at the average of the last seven days. Forecast and actual thresholds fire independently.

Each new alert:

  • is shown on the Budgets page under "Fired this period";
  • is sent as the event Budget Threshold Crossed (source ews.billing, detail.kind actual or forecast) to the organization's default event bus, where an event rule can route it;
  • is e-mailed to the budget's notification addresses, if it has any.

A budget whose scope points at a project or saved view that no longer exists has a broken scope: it is evaluated as spending nothing and fires no alert.

A budget that guards nothing

A scope that selects nothing looks like a scope that guards something until the period ends. The Budgets page and GET /billing/api/budgets/status say when a budget's scope selects no billable resource. Check a scope while you create the budget (see Create a budget).

Limits

  • At most 10 tag clauses per scope, and 10 forecast thresholds.
  • Thresholds are whole percentages from 1 to 1000.
  • The number of budgets is a quota (see Quotas).
Did this page help you?