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