Budgets

Budgets enable administrators to set spending limits with configurable thresholds, enforcement actions, and scope levels. Budgets can be applied at the platform level, per user, or per resource group, providing layered cost control across the organization.

Budget Structure

Each budget consists of the following components:

Scope

Budgets are scoped to one of three levels:

Scope Level	Description
platform	Applies to all resources across the entire platform
user	Applies to resources owned by a specific user
resourceGroup	Applies to resources within a specific resource group

The scope object includes:

Field	Description
level	One of platform, user, or resourceGroup
userId	User ID (for user-scoped budgets)
userName	Display name of the user (cached)
resourceGroupId	Resource group ID (for group-scoped budgets)
resourceGroupName	Display name of the group (cached)

Budget Amount

Field	Description
amount	Budget amount in cents (e.g., 100000 = $1,000.00)
currency	Currency code (e.g., USD)
period	Budget period: daily, weekly, or monthly
resetDay	Day of the period when the budget resets (e.g., 1 for the 1st of the month)

Thresholds

Thresholds define percentage breakpoints where actions are triggered. Each budget can have multiple thresholds:

Field	Description
percent	Percentage of budget at which to trigger (e.g., 50, 80, 100)
action	Action to take: alert, soft_stop, or hard_stop

Default thresholds (applied when no custom thresholds are specified):

• 50% -- alert (early warning notification)
• 80% -- alert (approaching budget limit notification)
• 100% -- hard_stop (budget exceeded, enforcement action)

Threshold Actions

Action	Behavior
alert	Send a notification to budget owner and administrators. No resources are affected.
soft_stop	Send a notification and flag resources for review. Resources continue running but are marked as over-budget.
hard_stop	Send a notification and stop resources that are contributing to the overage. This is the most aggressive enforcement action.

Enforcement Settings

Field	Description
stopAction	Default threshold action when the budget is exceeded
notifyOwner	Whether to notify the budget owner when thresholds are reached
notifyAdmins	Whether to notify all administrators when thresholds are reached

Usage Tracking

Each budget tracks current usage:

Field	Description
current	Current spend in the period (in cents)
percentUsed	Percentage of budget consumed
periodStart	Start of the current budget period
periodEnd	End of the current budget period
lastUpdated	When the usage was last updated

Budget Status

Status	Description
active	Budget is enabled and tracking spending
paused	Budget is temporarily disabled (not tracking or enforcing)
exceeded	Budget has been exceeded and enforcement actions have been triggered

Creating a Budget

Via the UI

1. Navigate to FinOps then Budgets
2. Click Create Budget
3. Configure the budget:

Basic Information:

• Name -- Descriptive name (e.g., "Q1 2025 Development Team Budget")
• Description -- Optional description of the budget's purpose

Scope:

• Platform -- Applies to all platform resources
• User -- Select a specific user from the dropdown
• Resource Group -- Select a resource group from the dropdown

Budget Configuration:

• Amount -- Dollar amount for the budget period
• Currency -- Select currency (default: USD)
• Period -- Daily, weekly, or monthly
• Reset Day -- Day within the period when the budget resets

Thresholds:

• Add one or more threshold breakpoints
• For each threshold, set the percentage and the action (alert, soft stop, or hard stop)

Enforcement:

• Stop Action -- Default action when budget is exceeded
• Notify Owner -- Send notifications to the budget owner
• Notify Admins -- Send notifications to all administrators

4. Click Create Budget

Budget Methods

Method	Parameters	Description
budgets.create	{ name, description, scope, budget, thresholds, enforcement, enabled }	Create a new budget
budgets.get	budgetId	Get a budget by ID
budgets.list	{ scopeLevel, status, search, skip, limit }	List budgets with filters
budgets.update	budgetId, { name, description, scope, budget, thresholds, enforcement, enabled }	Update a budget
budgets.delete	budgetId	Delete a budget

All budget methods require admin role access.

Managing Budgets

Filtering and Searching

The budget list supports the following filters:

• Scope Level -- Filter by platform, user, resourceGroup, or all
• Status -- Filter by active, paused, exceeded, or all
• Search -- Text search on budget name (case-insensitive, regex-safe)
• Pagination -- skip and limit for paging through results

Results are sorted by creation date (newest first).

Pausing and Resuming

Temporarily disable a budget without deleting it:

Pause:

budgets.pause(budgetId)

Sets enabled: false and status: 'paused'. The budget stops tracking spending and enforcing thresholds.

Resume:

budgets.resume(budgetId)

Sets enabled: true and status: 'active'. The budget resumes tracking from where it left off.

Resetting a Budget Period

Reset the current usage to zero and start a new budget period:

budgets.reset(budgetId)

This sets:

• usage.current to 0
• usage.percentUsed to 0
• usage.periodStart to the current timestamp
• status back to active

Use this when you need to manually reset a budget period (e.g., after adjusting the budget amount mid-period).

Budget Summary

Get an overview of all budgets:

budgets.getSummary()

Returns:

Field	Description
total	Total number of budgets
active	Number of active budgets
paused	Number of paused budgets
exceeded	Number of exceeded budgets
totalBudgetAmount	Sum of all budget amounts
totalCurrentSpend	Sum of all current spending
avgPercentUsed	Average percentage used across all budgets

Alert History

Budget alerts are stored in the resource_budget_alerts collection:

Field	Description
budgetId	Which budget triggered the alert
type	Alert type: threshold_reached, budget_exceeded, resource_stopped, budget_reset
threshold	The threshold percentage that was triggered
currentUsage	Current usage at the time of the alert
budgetAmount	Budget amount at the time of the alert
affectedResources	Array of resources affected by enforcement actions
notification	Notification delivery status (email sent, recipients, in-app sent, timestamp)
createdAt	When the alert was generated

Stopped Resources

When a hard_stop threshold is triggered, the affected resources are recorded:

Field	Description
resourceType	Type of resource that was stopped
resourceId	ID of the resource
resourceName	Display name of the resource
stoppedAt	When the resource was stopped
stoppedBy	Who (or what system) stopped the resource
currentSpend	Current spend at the time of stop
budgetAmount	Budget amount at the time of stop

Budget Examples

Platform-Wide Monthly Budget

A budget covering all platform resources with escalating thresholds:

• Scope: Platform
• Amount: $10,000/month
• Thresholds:
  • 50% ($5,000) -- Alert
  • 80% ($8,000) -- Alert
  • 100% ($10,000) -- Hard stop
• Enforcement: Notify owner and admins

Per-User Development Budget

A budget limiting individual developer spending:

• Scope: User (specific developer)
• Amount: $500/month
• Thresholds:
  • 75% ($375) -- Alert
  • 100% ($500) -- Soft stop
• Enforcement: Notify owner only

Resource Group Project Budget

A budget for a specific project's resources:

• Scope: Resource Group ("Customer Analytics Project")
• Amount: $2,000/weekly
• Thresholds:
  • 50% ($1,000) -- Alert
  • 90% ($1,800) -- Alert
  • 100% ($2,000) -- Hard stop
• Enforcement: Notify owner and admins

Best Practices

Set Up Layered Budgets

Create budgets at multiple scope levels for comprehensive cost control:

1. Platform budget -- Overall spending cap for the entire organization
2. Team/group budgets -- Per-resource-group budgets for each team or project
3. User budgets -- Individual developer spending limits for development environments

Configure Multiple Thresholds

Use at least three thresholds per budget:

1. 50% -- Early warning to start reviewing spending
2. 80% -- Approaching limit, take corrective action
3. 100% -- Budget exceeded, enforcement kicks in

Start with Alert-Only

When creating new budgets, start with alert actions at all thresholds. This lets you understand spending patterns before enabling enforcement. After a few budget periods, adjust thresholds and add soft_stop or hard_stop actions as appropriate.

Review Budget Performance Regularly

• Check the budget summary weekly to identify budgets approaching their limits
• Review exceeded budgets to understand root causes
• Adjust budget amounts based on actual spending patterns
• Reset budgets manually if mid-period adjustments are needed

Coordinate with Resource Schedules

Combine budgets with resource schedules for maximum cost control:

• Use schedules to automatically reduce costs during off-hours
• Use budgets to catch unexpected spending that exceeds schedule savings
• Set budget thresholds based on expected post-schedule spending levels

warning

hard_stop enforcement will stop running resources when the budget is exceeded. Use this action carefully in production environments. Consider using soft_stop or alert for production budgets and reserving hard_stop for development and staging environments.