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

# Policies and budgets

> Policies trigger alerts or actions based on usage patterns. Budgets set token or cost limits at the org or department level with real-time enforcement.

Toktra gives you two complementary tools for controlling AI usage: **policies** for event-driven rules, and **budgets** for spending limits. Both are configurable from the dashboard and available via the [Public API](/api/policies).

## Policies

A policy is a rule that watches the event stream and takes an action when specific conditions are met. You define what to look for (conditions) and what to do about it (actions).

### Policy conditions

Each policy has a trigger type and one or more conditions that narrow when the policy fires.

**Trigger types:**

| Trigger               | When it fires                                             |
| --------------------- | --------------------------------------------------------- |
| Token budget exceeded | A user or department crosses a usage threshold            |
| IP risk event         | GitHub integration detects a potential IP leakage event   |
| Unusual usage pattern | Usage deviates significantly from a user's baseline       |
| Department threshold  | A department's aggregate usage crosses a configured limit |

**Condition fields** let you filter further — matching on risk level, user ID, department, token count, time of day, or model ID. Multiple conditions can be combined with **AND** (all must match) or **OR** (any must match).

Example: a policy that fires only for high-severity IP risk events from the Engineering department:

```text theme={null}
Trigger: IP risk event
Conditions (AND):
  risk_level = high
  department_id = engineering
```

### Policy actions

When a policy fires, it can take one or more actions:

| Action                      | What it does                                          |
| --------------------------- | ----------------------------------------------------- |
| Send email to user          | Notifies the user whose activity triggered the policy |
| Send email to manager       | Notifies the user's manager                           |
| Block LLM access (hard cap) | Immediately stops the user's LLM requests             |
| Create incident             | Opens a new incident in Toktra's incident tracker     |
| Webhook POST                | Sends a JSON payload to a URL you configure           |

You can stack multiple actions on a single policy — for example, create an incident *and* send an email to the manager.

### Policy lifecycle

Policies are created as **drafts** and must be **published** to become active. You can **test** a policy against historical data before publishing — the test shows how many events in the last evaluation window would have triggered the policy. Active policies can be **disabled** without deleting them.

<Tip>
  Use the test function to tune condition thresholds before publishing. A policy with overly broad conditions can generate noise that drowns out real signals.
</Tip>

## Budgets

Budgets set limits on how many tokens — or how much money — a department or the whole organization can spend in a given period. When a budget is reached, Toktra can warn, alert, or hard-block further requests.

### Department hierarchy

Budgets are organized around your department hierarchy. Departments can be nested: a parent department's budget is the aggregate of its children. If Engineering has a budget of 10 million tokens and has sub-departments (Backend, Frontend, Data), each sub-department has its own budget that rolls up to the Engineering total.

You configure the hierarchy in **Budget Management → Department Hierarchy**. The dashboard shows a collapsible tree view of departments with live usage gauges.

### Soft caps vs. hard caps

Each budget can be configured as a **soft cap** or a **hard cap**.

| Cap type | What happens at the limit                                                                                      |
| -------- | -------------------------------------------------------------------------------------------------------------- |
| Soft cap | An alert is triggered. Requests continue.                                                                      |
| Hard cap | All LLM requests from users in that department are blocked until the budget resets or an exemption is granted. |

<Warning>
  Hard caps enforce at the agent level — the Chrome extension performs a sub-200ms preflight check before sending requests. Requests that exceed the cap are blocked before they reach the LLM provider. Ensure your team is aware before enabling hard caps on production departments.
</Warning>

### Budget rollovers

Budgets can be configured to roll over unused tokens month-to-month. You set a rollover cap percentage — for example, 50% means that up to half of the unused monthly budget carries forward. This prevents departments from losing tokens they didn't use without incentivizing wasteful end-of-month spending.

Rollover history is visible in **Budget Management → Rollover History**.

### Budget exemptions

When a hard cap blocks a user who has a legitimate need, they or their manager can submit a **budget exemption request** through the dashboard. Exemption requests route to an admin approver. Approved exemptions temporarily raise or lift the cap for the specified user and period.

Manage exemptions at **Budget Management → Exemptions**.

<Info>
  Exemption requests are logged in the audit trail regardless of outcome. Admins can see who requested exemptions, who approved them, and for what period.
</Info>

## Policies vs. budgets

Both policies and budgets can trigger alerts, but they serve different purposes:

|                     | Policies                                       | Budgets                                |
| ------------------- | ---------------------------------------------- | -------------------------------------- |
| **Primary purpose** | Event-driven governance rules                  | Spending limit enforcement             |
| **Evaluated**       | In real time, per event                        | Continuously against cumulative totals |
| **Scope**           | Flexible (user, department, model, risk level) | Department or org                      |
| **Actions**         | Alert, block, create incident, webhook         | Alert (soft cap), block (hard cap)     |
| **Resets**          | Never (stateless per evaluation)               | Monthly (with optional rollover)       |

In practice, most organizations use both: budgets to enforce overall spending limits, and policies to respond to specific events like IP risk detections or unusual usage spikes.