> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Budget enforcement
> Create org and department budgets, enforce hard caps, manage exemptions, and track spend in real time.
Toktra's budget enforcement system lets you set token spending limits at the organization and department level, block requests the moment a cap is reached, and give users a path to request additional tokens when they need more.
## How budgets work
Budgets are denominated in **tokens** and reset at the start of each monthly period. Toktra tracks consumption in real time for sub-200ms preflight checks and reconciles against authoritative provider data for reporting.
Two enforcement modes are available:
| Mode | Behavior |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Soft cap** | Usage above the budget triggers an alert but requests are not blocked. |
| **Hard cap** | Once the budget is exhausted, outbound LLM requests are blocked by the Chrome extension and the macOS/Windows agents. The block lifts when the period rolls over or an exemption is approved. |
Hard cap enforcement is applied at the agent and browser extension layer. A hard-capped user will see an inline message indicating their budget is exhausted. All blocked requests are logged in the audit trail.
## Creating an org-level budget
Go to **Budget** in the sidebar.
To create an org-wide budget, use a department name like `Org` or map it to your top-level hierarchy node.
Enter the token allowance. For example, to allow 50 million tokens per month for the entire org, enter `50000000`.
Enable **Hard Cap** to block requests once the budget is exhausted. Leave it unchecked for soft cap (alert only).
Click **Create Budget**. The budget takes effect immediately.
## Creating a department-level budget
Department budgets let you allocate different token allowances to different teams — for example, 5 million tokens/month for Marketing and 20 million tokens/month for Engineering.
On the **Budget** page, click **Add Department Budget**.
Type the department name, such as `Engineering`. If the department does not exist yet, Toktra creates it automatically.
Enter the monthly token allowance. For example, enter `20000000` for a 20 million token/month limit for Engineering.
Enable **Enable Rollover** to carry unused tokens into the next month. Set **Rollover Cap (%)** to limit how much rolls over — for example, `50` means up to 50% of unused tokens carry forward.
Click **Create Budget**. The department appears immediately in the hierarchy view.
## Hierarchical department budgets
Toktra supports nested department structures. For example:
```
Engineering (20M tokens/month)
├── Backend (8M tokens/month)
├── Frontend (6M tokens/month)
└── Data Science (6M tokens/month)
```
Budgets roll up the hierarchy: a sub-department cannot consume more than its own budget regardless of the parent's remaining balance. The **Department Hierarchy** tree on the Budget page shows each node's usage gauge, cap type, and current consumption.
The Chrome extension performs a budget validation in under 200ms before every LLM request using cached hierarchy data. Enforcement is transparent and does not noticeably delay requests.
## Budget periods
Toktra resets department budgets monthly. On the first of each month, Toktra automatically calculates and transfers any allowed carryover into the new period's starting balance.
Quarterly budgets can be approximated by setting the monthly budget to one-third of the quarterly target. Native quarterly period support is on the roadmap.
## Budget alerts
When consumption crosses configurable thresholds, Toktra sends alerts via email and Slack. Toktra continuously monitors spend against every active budget and triggers alerts when usage crosses the thresholds you define (for example, 70% and 90% consumed).
To create a department budget via the API with rollover enabled:
```json theme={null}
POST /v1/budgets/departments
{
"department_name": "Engineering",
"monthly_token_budget": 20000000,
"hard_cap": true,
"rollover_enabled": true,
"rollover_cap_pct": 0.5
}
```
## Viewing spend vs. budget
The **Budget** page displays four summary cards:
| Card | Description |
| ---------------- | --------------------------------------------------------- |
| Org Total Budget | Sum of all department token budgets for the current month |
| Org Total Used | Tokens consumed this month across all departments |
| Top Department | The department with the highest token consumption |
| Your Budget | The signed-in user's remaining personal budget |
Below the summary cards, the **Department Hierarchy** tree renders each department with a usage gauge. The gauge turns amber at 70% and red at 90% consumption. Hard-capped departments display a shield icon; soft-capped departments show a warning triangle.
## Budget exemption requests
When a user needs more tokens than their budget allows — for example, during a sprint requiring intensive AI assistance — they can submit a **budget exemption request**.
### Submitting a request
Go to **Budget → Exemptions**.
Fill in the user ID, the reason for the request, the number of additional tokens needed, and the budget period.
Click **Submit Request**. The exemption enters **Pending** status and notifies the admin review queue.
### Approving or denying a request
Admins see a banner at the top of the Exemptions page showing the count of pending requests.
Navigate to **Budget → Exemptions**.
Locate the pending exemption. Click the green checkmark to **Approve** or the red X to **Deny**.
Enter a note to explain the decision. Notes are visible to the requester.
Click **Approve** or **Deny**. Approving an exemption takes effect immediately — the agent picks up the new allowance on the next request.
Filter the exemptions table by status — All, Pending, Approved, Denied, or Expired — to focus on items that need action.
Exemption states:
| Status | Meaning |
| -------- | ------------------------------------------------------------------------------ |
| Pending | Awaiting admin review |
| Approved | Additional tokens granted; user's effective budget is increased for the period |
| Denied | Request rejected; user's budget remains unchanged |
| Expired | Request was not reviewed before the period ended |
## Budget rollover configuration
To enable rollover for a department:
1. Open or create the department budget.
2. Check **Enable Rollover**.
3. Set **Rollover Cap (%)** — the maximum fraction of unused tokens that carry forward. For example, a department that uses 8M of a 10M monthly budget has 2M unused; with a 50% cap, 1M tokens roll into next month.
View rollover history in the **Rollover History** table at the bottom of the Budget page. Each row shows the period, entity type, base budget, tokens used, and the actual amount rolled over.
## ROI calculator
Navigate to **Performance → ROI Calculator** to project cost savings from budget adjustments. Enter your token volumes, model mix, and per-token costs to model what you could save by shifting workloads to more efficient models or tightening allocations for low-usage departments.