Skip to main content

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.

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:
ModeBehavior
Soft capUsage above the budget triggers an alert but requests are not blocked.
Hard capOnce 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

1

Navigate to Budget Management

Go to Budget in the sidebar.
2

Click Add Department Budget

To create an org-wide budget, use a department name like Org or map it to your top-level hierarchy node.
3

Set the monthly token budget

Enter the token allowance. For example, to allow 50 million tokens per month for the entire org, enter 50000000.
4

Choose enforcement mode

Enable Hard Cap to block requests once the budget is exhausted. Leave it unchecked for soft cap (alert only).
5

Save

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.
1

Click Add Department Budget

On the Budget page, click Add Department Budget.
2

Enter the department name

Type the department name, such as Engineering. If the department does not exist yet, Toktra creates it automatically.
3

Set the token budget

Enter the monthly token allowance. For example, enter 20000000 for a 20 million token/month limit for Engineering.
4

Configure rollover (optional)

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.
5

Save

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: 
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:
CardDescription
Org Total BudgetSum of all department token budgets for the current month
Org Total UsedTokens consumed this month across all departments
Top DepartmentThe department with the highest token consumption
Your BudgetThe 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

1

Navigate to Budget Exemptions

Go to Budget → Exemptions.
2

Click Request Exemption

Fill in the user ID, the reason for the request, the number of additional tokens needed, and the budget period.
3

Submit

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.
1

Open the Exemptions page

Navigate to Budget → Exemptions.
2

Review the request

Locate the pending exemption. Click the green checkmark to Approve or the red X to Deny.
3

Add reviewer notes (optional)

Enter a note to explain the decision. Notes are visible to the requester.
4

Confirm

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:
StatusMeaning
PendingAwaiting admin review
ApprovedAdditional tokens granted; user’s effective budget is increased for the period
DeniedRequest rejected; user’s budget remains unchanged
ExpiredRequest 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.