Skip to main content

​
Live spend tracking

Token usage and cost are tracked in the spend_ledger, one row per agent invocation, with input tokens, output tokens, cost, model, and invocation type. Spend is attributable per entity and per actor — the agent or human that triggered the spend.

​
Setting a monthly cap

Budget monitoring measures spend against a monthly cap in US dollars — the real cost of your LLM calls (the cost_usd totals in the spend ledger), not a token count. Caps live in swarm.yaml (runtime config); the threshold percentages live in the flow’s policy.yaml. Set the cap at whichever scope you want to limit:
swarm.yaml
A scope is only watched when its cap is set above zero, so you can limit, say, per-entity spend without a global cap. See Configuration.

​
Thresholds

Threshold percentages are configured in policy.yaml. Crossing one emits platform.budget_threshold_crossed with a matching level:
policy.yaml
With global_monthly_cap: 500, a budget_warning_percent: 60 warns once this month’s real spend crosses $300. Monitoring is on only when both a cap and at least one threshold percentage are set; otherwise it is off.

​
Responding to an emergency

At the emergency threshold the runtime does not just warn you, it pauses all agent sessions on its own and raises a mailbox item, so spend stops before a human is even in the loop. From there a person can approve continued spend, pause the run, or stop it. Pausing ingress (swarm control pause --all) also halts new work while you decide.