Create a budget

Create a budget for the organization, a project, a saved view or a set of tags, choose when it alerts and who is mailed, and check what it covers before you save it.

Last updated 18 November 2026View as Markdown

A budget alerts; it never stops anything by itself (see Budgets). Replace Platform team with a name of your own, and jane.doe@example.com with the address to mail.

Prerequisites

  • Permission for billing:CreateBudget. Without it, the console says "Creating one needs billing:CreateBudget, which your policies do not grant."
  • In the console, also billing:GetBudgets to open Budgets (without it the page shows an access-denied notice).
  • To scope by tags, tags:ListTags; by a saved view, tags:ListProjects; by a project, projects:ListProjects. Without them the console offers only The whole organization, and says which permission the other choices need.
  • To check a scope before saving, billing:GetBudgets and tags:ListTags.
  • Room in the Budgets quota (see Quotas).

Create the budget

Budgets are free.

  1. Open Budgets, then choose Create budget.
  2. Under The alert, for Name, enter Platform team.
  3. For Alert me at (EUR), enter the amount, for example 500.
  4. For Period, choose Monthly, Quarterly or Annual.
  5. Under What it covers, choose The whole organization, A project, A saved view or Resources with a tag, and pick the project or view, or enter the tag keys and values. Below the choice, the form says how many billable resources the scope covers, or warns when it covers none.
  6. (Optional) Under Services, select the services to count. Leave all clear to count every service.
  7. Under Who hears about it, change Alert thresholds (the form starts at 80,100) and, for a monthly budget, Forecast thresholds (the form starts at 100).
  8. For Notification emails, keep your own address, which the form fills in, or enter others.
  9. (Optional) Under Suggest what to stop, select the check box to let the budget propose stopping non-production resources (see Let a budget propose stopping resources).
  10. Choose Create budget.

If you close the dialog before creating, what you typed is kept for the next time you open it.

The console and the API start from different defaults:

Field Console form API, CLI and Terraform
period Monthly Required
scope The whole organization The whole organization
alertThresholds 80, 100 [80, 100]
forecastThresholds 100 (monthly budgets only) None
notificationEmails Your own address None: alerts are recorded and sent as events, but not mailed

Check a scope before you save it

The console checks the scope as you type it. Over the API:

POST /billing/api/budgets/scope-preview
{ "scope": { "type": "tags", "clauses": [{ "key": "team", "values": ["platform"] }] } }

The answer says how many resources the scope selects (matched), how many of them are billed now (billable), by type, and valid: false with an error for a project or saved view that does not exist. Nothing is written.

Result

The budget exists and is evaluated every hour. It appears on Budgets with what it has used in the current period.

When creation is refused

  • 409 "Quota exceeded: Budgets (billing.budgets) — …" when the quota is used up.
  • 400 when a threshold is not a whole number from 1 to 1000, an address is not an e-mail address, or a tag key is not lowercase starting with a letter.

A project or saved view id that does not exist is accepted: the budget is created with a broken scope and watches nothing. A service id in serviceFilter that does not exist is accepted too and counts nothing.

Did this page help you?