> ## Documentation Index
> Fetch the complete documentation index at: https://yukta.infenia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set token budgets

> Cap the tokens, cost and tool calls of a model-driven run with a shared budget, and end the whole run when it is used up.

<dl />

**Use this when** a workflow calls a model, possibly in a loop of agent rounds, and you want a ceiling on tokens, money or tool calls.

**Prerequisites:** [Call an LLM](https://yukta.infenia.com/guides/ai/call-an-llm.md) works for you. Add `-H "X-API-Key: $YUKTA_API_KEY"` if your server has keys.

![Every model and tool node that shares an agent name draws on one budget. Without hardStop the next call fails like any failed call; with hardStop the whole run ends.](https://yukta.infenia.com/images/diagrams/guide-set-token-budgets.light.svg)

All the nodes that share an agent name spend from one ledger. hardStop turns a used-up budget from a failed node into an ended run.

## Steps

**1. Add a budget to each model node**

`budget` is a map on `LLM_CALL`: `maxTokens` (input plus output), `maxCost` (needs `prices`), `maxCalls` counts tool calls (for `MCP_TOOL_CALL`), `agent` names a shared ledger and `hardStop` decides what happens when it is used up.

```json theme={"system"}
{
  "nodeId": "plan",
  "type": "LLM_CALL",
  "config": {
    "provider": "anthropic", "model": "claude-sonnet-5-5", "apiKey": "decrypted:anthropic",
    "prompt": "${payload.text}",
    "maxTokens": 1024,
    "prices": { "input": 3.0, "output": 15.0 },
    "budget": { "maxTokens": 20000, "maxCost": 0.5, "agent": "triage", "hardStop": true }
  }
}
```

`prices` are per million tokens, in your own currency; use your provider's current rates. With `prices` set, the node's output also carries a `cost`.

**2. Share one ledger across nodes**

Every model and tool node of a run shares the budget. Give the same `agent` name to the nodes that belong together, and each agent is counted apart. Without `agent`, a run has one budget for all its nodes. `MCP_TOOL_CALL` supports `maxCalls`, `agent` and `hardStop` (no tokens or cost):

```json theme={"system"}
{ "nodeId": "act", "type": "MCP_TOOL_CALL",
  "config": { "url": "https://issues.example.com/mcp", "tool": "${payload.tool}",
              "budget": { "maxCalls": 4, "agent": "triage", "hardStop": true } } }
```

**3. Choose soft or hard**

Without `hardStop`, the next call after the budget is used up fails like any failed call, so retries, `failureMode`, fallback ports and error routing still apply. With `hardStop: true` the next call ends the **whole run**: it is not retried, dropped, routed or absorbed by `failureMode`. Use `hardStop` when overspend must never be absorbed.

**4. Test the ceiling with a tiny budget**

Set `"budget": {"maxTokens": 1, "hardStop": true}` on a second `LLM_CALL` chained after the first, start the workflow and watch the run end at the second call. Then restore your real numbers.

## Verify it worked

```bash theme={"system"}
curl -s localhost:9858/api/executions/$EXEC
curl -s "localhost:9858/api/executions/$EXEC/nodes/plan/output?tail=20"
```

With the tiny test budget, the first call succeeds and the second does not run: the run ends in a failed status with a budget error in the log, and no further model call is billed. Without `hardStop`, the second node ends `FAILURE` and the rest of the graph reacts as for any failure. With your real budget the node output includes `usage` and, with `prices`, `cost`. The **Control** dashboard shows tokens and spend per provider: [Use the Control dashboard](https://yukta.infenia.com/guides/supervise/use-the-control-dashboard.md).

## Variations

* **Know what counts.** The check runs before a call and the usage is added after it, so one call can overshoot, and calls running at the same time can each pass the check. `maxCalls` counts tool calls only.
* **Budgets are in memory.** They start again from zero after a restart or a resume.
* **Other guardrails.** A per-provider rate limit, prompt and answer filters and tool allow-lists are server and node settings: [Call an LLM](https://yukta.infenia.com/guides/ai/call-an-llm.md), [Use tools and MCP servers](https://yukta.infenia.com/guides/ai/use-tools-and-mcp-servers.md).
* **Cheaper decisions.** Small routing and gating choices cost far fewer tokens with a decision model: [Classify, gate and score](https://yukta.infenia.com/guides/ai/classify-gate-and-score.md).

## Related

* [AI plugins reference](https://yukta.infenia.com/reference/plugins/ai.md) for the `budget` and `prices` fields.
* [Configuration](https://yukta.infenia.com/reference/configuration.md) for `yukta.llm.*`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.