# Cost Management

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.

{% hint style="info" %}
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.
{% endhint %}

### Monthly Reset

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

### Fail-Open Behavior

{% hint style="info" %}
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.
{% endhint %}

### 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

{% hint style="info" %}
Budget status updates in real time during agent conversations. After each agent response, the indicator reflects the latest usage.
{% endhint %}

### 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

{% hint style="info" %}
Admin endpoints require admin-level permissions. All endpoints are accessed through the groundcover API gateway.
{% endhint %}

### 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:

```json
{
  "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:**

```json
{
  "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) |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/agent-mode/cost-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.