Hierarchical budgets: one ceiling at run, feature, department, and org level at once
Fifty agent runs at $0.49 each all pass their own $0.50 per-run limit individually. Their combined total — $24.50 — blows straight through a $20 department budget, and nothing catches it, because every single run, evaluated on its own, was compliant. The department ceiling only exists on paper if nothing is actually checking the department total against every run as it happens.
That gap is the reason a flat set of independent budgets — one per run, one per feature, one per department — isn't the same thing as a real hierarchy. A hierarchy means every call is checked against every applicable level at once, and the most restrictive one always wins, so the org ceiling can never be breached even when every individual child budget underneath it still technically has room.
Why independent budgets at each level don't add up to a hierarchy
Setting a $0.50 per-run limit and, separately, a $20 department limit looks like it should produce the same protection as a real hierarchy — both numbers exist, both are configured. The difference is what each check actually has visibility into. A per-run check only ever sees one run at a time; it has no way of knowing how many other runs already happened this month against the same department. A department check that only runs at month-end, against the accumulated total, catches the overspend after it's already happened rather than at the call that would have caused it.
A real hierarchy closes that gap by evaluating every level together, at the moment of the call — not each level independently, on its own schedule. The parent budget's remaining room is checked in the same atomic operation as the child budget's, so the department ceiling isn't a retrospective report, it's an active constraint on every single call that could contribute to it.
How the hierarchy is structured
Budgets carry an explicit scope — run, feature, department, or org — and an optional parent budget reference, so a child budget's spend rolls up to its parent's counter. The enforcement chain runs run → feature → department → org: a call is only allowed through if every matching level in that chain still has room. The parent ceiling always wins even when every child budget underneath it would individually still allow the call — that's the specific property a flat set of independent budgets cannot guarantee.
In practice this means setting an org-level budget as the hard ceiling — your total quarterly AI allocation divided into a monthly figure, typically in Degrade mode so the whole organization doesn't hard-stop the moment it's hit — then department budgets underneath it in Alert mode so teams manage their own spend day to day, then feature-level budgets in Block mode for experimental or agentic features specifically, and finally per-run sub-limits on top of the feature budget for anything that executes as a multi-step workflow. See the full step-by-step setup guide for the exact configuration at each level.
What the response actually tells you
Every call that passes through returns a x-cog-budget-remaining response header showing the most restrictive remaining budget across every level that applied to it — not just the level that happened to be checked first. For a long-running agent, polling a budget-status endpoint before each step lets the agent stop itself gracefully once any matching budget drops below a safety margin, rather than being cut off mid-execution by a hard block partway through a multi-step task.
This is also what makes choosing block, degrade, or alert mode per level a real design decision rather than a single global setting — an org-level budget in Degrade mode and a feature-level budget in Block mode can coexist in the same hierarchy, each doing the job appropriate to its scope.
What this looks like in practice
Consider a hypothetical engineering department with a $500 monthly budget and a document-processing agent underneath it with its own $200 feature budget and a $0.50 per-run sub-limit. Forty runs complete cleanly within their individual per-run limits over the course of a week — every one of them compliant on its own. But the department's total spend across all its features, including this one, is now approaching its own $500 ceiling faster than expected because of unrelated activity elsewhere in the department.
Because the hierarchy checks the department level on every call, not just the feature or run level, the forty-first run is blocked at the department boundary even though its own per-run and per-feature budgets both still have room — the parent ceiling caught what neither child budget was positioned to see. This is illustrative of how the hierarchy behaves, not a specific customer's reported outcome.
Hierarchical budgets set the org-wide ceiling that can never be breached. They complement, rather than replace, atomic run-level budgets for concurrent multi-agent workflows — the run-level mechanism stops a single run from overspending internally; the hierarchy stops many compliant runs from overspending in aggregate.