Cost Management

Control monthly Agent Mode spending with organization, default, and per-user cost limits

Admins can set monthly cost limits (in USD) at three levels to control Agent Mode spending across the organization. Budgets reset automatically at the start of each calendar month.

How Budgets Work

Budget Hierarchy

Cost management uses a three-tier budget hierarchy. Each tier is independent — configure any combination based on your needs.

Level	Scope	When Exceeded
Organization budget	All users in the organization combined	All users are blocked
Default per-user budget	Any user without an individual override	That user is blocked
Per-user override	A specific user (takes precedence over the default)	That user is blocked

Both the organization budget and the user-level budget are checked before each agent request. A user is blocked if either limit is reached.

If no budgets are configured, usage is unlimited. You can set an organization budget, a default per-user budget, per-user overrides, or any combination of the three.

Monthly Reset

Budgets reset at the start of each calendar month (UTC). Usage does not carry over from previous months.

Fail-Open Behavior

If the budget system is temporarily unavailable (for example, due to a database connectivity issue), agent requests are allowed to proceed. This ensures transient infrastructure issues do not block users.

Cost Calculation

Costs are calculated per token based on the model used for each request. Input tokens, output tokens, and cache tokens each have different rates. Cache read tokens are significantly cheaper than regular input tokens, and cache creation tokens are priced slightly above regular input.

The total cost of each agent request is the sum of input cost (regular + cache) and output cost. Costs are tracked automatically — no configuration is needed.

Configuring Budgets

Budget configuration requires an admin role. Navigate to Settings > Preferences > AI Features and scroll to the Cost Management section.

Month Picker

Use the month picker at the top of the section to view current or historical usage. Budget editing is only available for the current month — historical months are read-only.

Organization Budget

The organization budget sets an aggregate monthly cost cap across all users. When total usage reaches this limit, every user in the organization is blocked until the next month.

1. In the Cost Management section, find Organization monthly limit

2. Enter the dollar amount

3. Click Update

To remove the organization budget, click Remove. Without an organization budget, there is no aggregate cap.

Default Per-User Budget

The default per-user budget is a fallback limit applied to every user who does not have an individual override. When removed, users without overrides become unlimited.

1. In the Default per-user monthly limit area, enter the dollar amount

2. Click Update

To remove, click Remove.

Per-User Overrides

Per-user overrides let you set individual budgets that take precedence over the default. Use these to give specific users higher or lower limits.

Setting an override for an existing user:

1. Find the user in the Per-User Usage & Limits table (use the search filter to narrow results)

2. Click the edit icon next to their limit

3. Enter the dollar amount and confirm

Adding a new user override:

1. Click Add User

2. Select the user from the dropdown

3. Enter the dollar amount and confirm

Removing an override:

1. Click the remove icon next to the user's override

2. Confirm the removal

When an override is removed, the user falls back to the default per-user budget. If no default is set, the user becomes unlimited.

Understanding the Usage Table

The per-user table shows each user's current month usage with visual indicators:

Indicator	Meaning
Green progress bar	Under 75% of limit
Yellow progress bar	75%–99% of limit
Red progress bar	At or over 100% of limit
Blocked tag	User has reached their limit

Budget Status in the Chat

All users see their budget status below the chat input field. The status updates in real time as the agent processes requests.

• Progress bar with percentage — shows "X% of monthly budget used" when a budget is active

• "Limit reached" tag — shown in red when the budget is exceeded

Budget status updates in real time during agent conversations. After each agent response, the indicator reflects the latest usage.

What Happens When Blocked

When a budget is exceeded, the agent returns an error message instead of processing the request:

• User budget exceeded — the user sees a message with their current cost and limit

• Organization budget exceeded — all users see a message indicating the organization's monthly budget has been reached

The user cannot start new agent conversations until the next monthly reset or an admin increases or removes the budget.

API Reference

Admin endpoints require admin-level permissions. All endpoints are accessed through the groundcover API gateway.

Budget Configuration (Admin)

Method	Endpoint	Description
GET	/api/agent/token-budgets	List all configured budgets
PUT	/api/agent/token-budgets/tenant	Set organization budget
DELETE	/api/agent/token-budgets/tenant	Remove organization budget
PUT	/api/agent/token-budgets/default	Set default per-user budget
DELETE	/api/agent/token-budgets/default	Remove default per-user budget
PUT	/api/agent/token-budgets/users/{user_id}	Set per-user override
DELETE	/api/agent/token-budgets/users/{user_id}	Remove per-user override

Request body for PUT endpoints:

{
  "monthly_cost_limit": 25.00
}

The monthly_cost_limit value is in USD and must be greater than zero.

Usage Reporting (Admin)

Method	Endpoint	Description
GET	/api/agent/token-usage	All users' usage for a month
GET	/api/agent/token-usage/tenant	Organization total usage
GET	/api/agent/token-usage/{user_id}	Specific user's usage
GET	/api/agent/token-usage/history	Multi-month usage history

All usage endpoints accept an optional month query parameter in YYYY-MM format (defaults to the current month). The history endpoint accepts months (default: 12).

Budget Status (Any User)

Any authenticated user can check their own budget status:

GET /api/agent/token-budget/status

Response:

{
  "allowed": true,
  "cost": 12.50,
  "limit": 25.00,
  "remaining": 12.50
}

Field	Type	Description
allowed	boolean	Whether the user can make agent requests
cost	number	Current month's accumulated cost in USD
limit	number or null	Effective monthly limit (null means unlimited)
remaining	number or null	Remaining budget in USD (null means unlimited)