Manage budgets
| Budget controls are available for Scale Plan customers. |
Budget controls help you manage and monitor your CircleCI credit usage by setting spending limits at the organization and project level. With real-time tracking and automated notifications, you can ensure your CI/CD costs stay within expected ranges while maintaining visibility across your team.
What are budget controls?
Budget controls allow you to:
-
Set weekly budget limits for your entire organization or individual projects.
-
Track credit consumption in real-time as a percentage of your budget.
-
Receive automated notifications at 70%, 90%, and 100% of your budget. See Budget notifications.
Budgets run on weekly cycles from Monday 00:00:00 UTC through Sunday 23:59:59 UTC and reset automatically each week.
What counts towards budgets?
| User seat charges are excluded from budget limits, as these are fixed organizational costs rather than consumption-based project work. |
Your budget limits track credits consumed across:
-
Compute usage for all execution environments (Docker, machine, macOS, Windows, GPU, Arm).
-
Docker Layer Caching (DLC) usage.
-
Storage costs for artifact and workspace storage.
-
IP ranges usage, to restrict traffic to specific IP ranges.
-
Network usage, data transfer costs.
-
AI agents usage.
Budget notifications
We notify you when an organization or project approaches or reaches its weekly budget.
At 70% of a budget:
-
In-app banner. Organization budget banners appear on every page of the web app and are visible to everyone in the organization. Project budget banners appear on the project page.
-
Build notification emails. A budget warning is added to build notification emails for users who have opted in to My Work notifications.
At 90% and 100% of a budget:
-
In-app banner. The banner copy changes to reflect the higher usage level.
-
Build notification emails. Build notification emails include an updated budget warning for users who have opted in to My Work notifications.
| Budgets are soft limits. Builds keep running after you reach or exceed your budget. |
Budgets and child organizations
If your organization has child organizations:
-
You can set budgets only on the parent organization’s plan, not on the child organization’s plan. A parent organization budget includes credit usage from its child organizations.
-
Budget banners do not appear in the web app for child organizations.
-
You cannot set project budgets on projects that belong to child organizations.
Prerequisites
To use budget controls, you need:
-
A CircleCI Scale Plan.
-
Organization administrator permissions to create, edit, or delete budgets.
-
Access to the Plans page to view budget status.
Setting up budget controls
The following steps show you how to set up budget controls for your organization and projects.
Create an organization budget
-
In the CircleCI web app, select your organization.
-
Navigate to Plan in the CircleCI web app sidebar and select Usage Controls.
-
Go to the Credit Budgets section.
-
Select Add organization budget to open the add organization budget modal.
-
Enter your weekly credit limit in the text field.
-
Select Save.
Create a project budget
-
In the CircleCI web app, select your organization.
-
Navigate to Plan in the CircleCI web app sidebar and select Usage Controls.
-
Go to the Credit Budgets section.
-
Select Add project budget to open the add project budget modal.
-
Search for your project by name.
-
Enter your weekly credit limit in the text field.
-
Select Save.
Edit a budget
-
In the CircleCI web app, select your organization.
-
Navigate to Plan in the CircleCI web app sidebar and select Usage Controls.
-
Go to the Credit Budgets section.
-
Locate the budget you want to edit (organization or project).
-
Select the corresponding budget edit icon
.
-
Update the credit budget limit in the text field.
-
Select Save.
Delete a budget
-
In the CircleCI web app, select your organization.
-
Navigate to Plan in the CircleCI web app sidebar and select Usage Controls.
-
Go to the Credit Budgets section.
-
Locate the budget you want to delete (organization or project).
-
Select the corresponding budget trash bin icon
.
-
Confirm the deletion by selecting Delete budget.
| Deleting a budget immediately stops budget tracking and removes all budget notifications for that organization or project. Budget consumption data from previous cycles is not deleted. |
Advanced cost tracking
For detailed cost analysis across multiple platforms, consider integrating with Vantage or Finout. These tools provide unified cost tracking for CircleCI alongside your cloud infrastructure and SaaS providers, with features including:
-
Cost allocation by team, department, or business unit.
-
Historical cost trends and anomaly detection.
-
Cross-platform cost correlation and reporting.
See the Integrate CircleCI With Vantage and Integrate CircleCI With Finout guides for more information.