# Daily budget per agent

> Limit how many model tokens an agent uses per UTC day, watch it in observe first, then hold or deny the agent once the limit is reached.

Source: https://docs.atensecurity.com/docs/operations/daily-budget

A daily budget limits what an agent spends in one UTC day, so a stuck loop or a runaway agent stops at a
number you chose. It counts **tokens** first. Dollars count only when the agent reports them: Thoth never
works out a dollar figure from tokens, because prices change.

A budget is a [policy rule](https://docs.atensecurity.com/docs/operations/policy-rules) of type `budget`, so an org admin approves it and
every path that reaches policy rules reaches it. The rule's `enforcement` decides what happens:

| `enforcement` | What the budget does |
| --- | --- |
| `monitor` | **Observe.** Records the calls it would have held, changes nothing. Start here |
| `review` | **Enforce, hold.** Once the limit is reached the agent's next calls wait for a person to approve them |
| `block` | **Enforce, deny.** Once the limit is reached the agent's next calls are denied |

`applied_to` names the agents (`all` for every agent). The rule carries only the budget: it has no tool
match, because the budget is for the whole agent.

```json
{
  "type": "budget",
  "enforcement": "monitor",
  "applied_to": ["support-agent"],
  "rules": { "daily_token_limit": 500000 }
}
```

| Key | Meaning |
| --- | --- |
| `daily_token_limit` | Whole tokens (prompt plus completion) per UTC day, 1 to 1,000,000,000,000 |
| `daily_cost_usd_limit` | Optional dollars per UTC day, counted only from dollars the agent reports |
| `hold_when_unreported` | Optional, `false` by default. See [When usage is not reported](#when-usage-is-not-reported) |

At least one limit is required. If an agent has several budget rules, the strictest applies: the lowest
limits, enforce over observe, deny over hold.

## Create a budget

The same rule is made the same way on every path; the keys go in `rules`.

```hcl
resource "thoth_policy" "support_budget" {
  environment = "prod"
  name        = "Daily token budget"
  type        = "budget"
  enforcement = "monitor" # review to hold, block to deny
  applied_to  = ["support-agent"]
  rules_json  = jsonencode({ daily_token_limit = 500000 })
}
```

```bash
thothctl governance policies create --environment prod --name "Daily token budget" \
  --type budget --enforcement monitor --applied-to support-agent \
  --rules '{"daily_token_limit": 500000}'
```

The MCP server's `preview_policy_rule` takes the same `type`, `enforcement`, `applied_to` and `rules`;
the preview says in words what the budget will do before you confirm. Start in `monitor`, read the usage
for a few days, then change `enforcement` to `review` or `block`.

## What counts, and when

The agent reports the model usage of the step that led to a governed call, in the fields the decision API
already accepts: `prompt_tokens` and `completion_tokens` (or `token_count`), and `estimated_cost_usd` if it
knows a dollar figure. Thoth adds that usage to the agent's total for the current UTC day.

The check happens **before** the call, using the total so far:

- A call that carries the usage that takes the agent over the limit **still runs**.
- The **next** call is held or denied.

So the limit is approximate by one call, and by any calls in flight at the same moment on different
replicas. Treat it as a stop for runaway spend, not as a billing meter. The day is the UTC date; at
00:00 UTC every agent starts again from zero. A budget is checked in observe-mode agents too, but an agent
in observe mode is never held or denied: the budget records what it would have done.

The budget trusts the usage the agent reports. It is a control against runaway agents (a loop, a
stuck retry, a misconfigured model), not against a hostile agent that under-reports: Thoth cannot verify
a model's token count, and does not guess one from the request. A report of zero counts as no report, so
sending zeros neither adds usage nor keeps `hold_when_unreported` quiet.

The budget applies to every call that reaches a decision, including calls to an approved MCP vendor that
would otherwise pass straight through, and a policy exception for a tool does not lift a budget hold or
deny. A budget never softens an earlier deny. A held call can be approved by a person, which lets that
one call run (the approval is recorded on the hold, and the hold's decision evidence carries the budget
record); that is the only way past a budget hold. A budget deny creates no hold, so nothing approves it. Calls refused before policy evaluation (quarantine, an
unauthenticated call, an unapproved MCP vendor) are not counted. Approving a held call does not run the
budget again.

Usage is counted per agent from the identity the request was authenticated as. An agent cannot read, reset
or add to another agent's or workspace's total, and a call that omits usage changes nothing. A value that is
negative, not a number or not finite counts as nothing; a single report is capped at 10,000,000 tokens and
$1,000.

## Report usage from your agent

Call the SDK helper after each model response, before the governed tool call it led to. The SDK sends the
usage with that next call, once.

```python
import thoth

response = client.chat.completions.create(...)
thoth.report_usage_from(response)  # OpenAI-style or Anthropic-style usage block
# or thoth.report_usage(prompt_tokens=1200, completion_tokens=300)
```

```go
client.ReportUsage(thoth.Usage{PromptTokens: 1200, CompletionTokens: 300})
```

The Python and Go SDKs have this helper. For other clients, send `prompt_tokens` and `completion_tokens` in the
decision request yourself.

Report dollars (`cost_usd` in Python, `CostUSD` in Go) only if you know them; Thoth never works a dollar
figure out from tokens.

## When usage is not reported

An agent that does not report usage has nothing for the budget to count. By default Thoth does **not** hold
such an agent: a call without usage counts as zero, and the usage read (below) says `usage_not_reported`
when the agent made calls today and none carried usage, so a budget that cannot work is visible rather than
silently reassuring.

Set `hold_when_unreported` to `true` to hold calls that arrive without usage when the agent has reported
none in the last hour (or none yet today). The trade-off: with it off, an agent that stops reporting
usage is never stopped by its budget; with it on, an agent that cannot report usage (an SDK or tool
that does not send it) is held until a person approves each call, and an agent that makes several tool
calls from one model response is not held, because the first call of the batch carried the usage.

## If the counter cannot be read

Counters live in MongoDB, one document per agent per UTC day, holding only totals: tokens, reported
dollars, call counts and the time usage was last reported. No arguments, prompts or model output are stored.
A document expires seven days after its day ends.

If the counter cannot be updated in time, an **enforcing** budget holds the call for review (reason code
`daily_budget_unavailable`), never denies it, because a storage error is not evidence of overspend. An
**observing** budget records that it could not count and changes nothing.

## Decisions and evidence

A held call has the reason code `daily_budget_reached` (or `daily_budget_usage_not_reported`) and the
decision evidence carries a `daily_budget` record with the mode, the limit and the total before the call,
never an argument value. For an agent in observe mode, the calls the budget would have held appear in
the [observe summary](https://docs.atensecurity.com/docs/operations/enforcement-modes) next to the other would-have decisions.

Policy simulation reads today's total and never adds to it. Replay does not model the budget and does not
touch the counters.

## See it in the dashboard

An agent's page has a **Daily budget** section. For an agent with a budget it shows today's tokens against the
limit, whether the budget is observing or enforcing, the calls it held and the calls it would have held,
and the last seven UTC days. If the agent made calls today and none carried usage, it says **Usage not
reported** instead of "0 used", and points here. An agent without a budget shows "No daily budget". The
Policy rules table in Settings, Governance reads a budget as "Budget: 500,000 tokens per day" with
Observe, Hold or Deny. The figures are the same approximate, client-reported counters described above.

`GET /{tenant}/thoth/v1/agents/{agent}/daily-budget` returns the agent's budget, today's usage with the
calls held or that would have been held, whether usage is being reported, and the last seven days. It needs the same access as the agent's
observe summary.
