--- title: "Capability: Spend controls" canonical_url: "https://tokenobserve.com/platform/spend-controls" published: 2026-09-02 last_updated: 2026-10-21 --- # Capability: Spend controls Hard USD ceilings, per-minute rate limits and a kill switch, all decided before the request leaves your network. ## What it is Token Observe enforces hard USD ceilings on any governed agent you set one on (per request, per rolling hour, per UTC day and per UTC month) and refuses a call that would cross one before it reaches a provider. The money verdict is taken last: permissions, rate limits and policy are decided first, then the route is resolved, then every provider and fallback it could execute is priced and the dearest of those rates is reserved in one transaction. A budgeted route with an unpriced target is refused before egress rather than priced at zero, because an empty price table is how the ceiling was once silently disarmed. Above it sits a kill switch scoped to one agent, one team or the whole estate. ## Facts - USD ceilings: Per request, hour, UTC day and UTC month - Rate ceilings: Requests, tool calls and tokens per minute - Kill-switch scope: One agent, one team, or everything - Shipped price rows: 50, loaded additively on every boot ## The limit What a hard ceiling costs you: One billable egress: no retry, no failover ## Why it exists: A budget that only reports is not a budget Most agent cost tooling is a dashboard. It tells you what you spent after you spent it: useful in a monthly review, useless at two in the morning when a retry loop is a third of the way through the month’s budget. The control a finance owner asks for refuses the call, and that needs a defensible price before it leaves the building. This product once shipped its price catalogue in the demo seeder that the setup documentation tells operators not to run, so the documented install started with an empty price table: every trace recorded $0 and every per-request ceiling admitted every request. The control was off while appearing to be on. So the price table is part of the control. A ceiling may be conservative. It may not be optimistic. ## How it works - Kill switch, before anything else: Step one of the pipeline finds any engaged switch reaching this subject and returns a 403, ahead of lifecycle status, permissions, budgets and policy. Team scope matches case-insensitively: a team name is typed by a human under pressure. - Rate limits decided in the pure pass: Requests, tool calls and tokens per minute return a 429 naming the limit, the configured value and the observed figure, and a blocked attempt is recorded before the refusal, so it is evidence rather than a free retry. USD is skipped here for any agent with a ceiling: money cannot be decided until routing fixes which upstream serves the call. - Resolve the route, then price everything it could reach: Route rules, tier selection and failover all change what may leave, so every fallback is priced alongside the primary against the resolved model: pricing the name the caller typed would leave a rerouted target as a zero-dollar escape hatch. Both legs are bounded upwards: the serialised request in bytes plus 256 tokens of framing, and the caller’s max_tokens or 4,096. - Serve a cheaper tier, never a dearer one: A deterministic heuristic (no classifier model, no learned weights) routes a request down a tier and never up. It needs the agent’s allowDowngrade flag and a confidence of at least 0.75, the maxTier ceiling applies regardless, and an unpriced model counts as reasoning tier so it cannot walk through the bound that caps it. - Admit atomically, then meter against the pinned price: One per-agent transaction reads the three USD windows, tests the projection and writes the reservation only if it clears, so two concurrent callers cannot both decide against the same window. Provider usage is then normalised into four mutually exclusive buckets (uncached input, cache read, cache write, output) and priced against the row pinned before egress. Providers disagree about whether cached tokens sit inside the prompt total, and getting that wrong misprices cache-heavy agent traffic badly. ## Where it runs in the request path Steps 6, 8 and 11 of the request path ## What it does not do - There is no team-level or fleet-level budget pool. Ceilings are enforced per governed subject; the team and fleet figures are the sum of the per-agent ceilings that exist, published beside a count of the agents that have none. - Nothing here is reconciled against a vendor invoice. Every figure is metered from the provider’s own reported usage against the price rows you hold (OpenRouter, which reports an authoritative charge, is the exception), and a shipped row is a list price captured on a date that will go stale. - A hard-budgeted call forgoes retry and failover after its one potentially billable egress. That is a deliberate availability cost in exchange for a spend boundary, and an agent with no USD ceiling does not pay it. - The retrospective savings report is degraded and should not be quoted. The automatic prompt excerpt it was built to read has been removed from the gateway, so it judges a call by token counts and whether tools were offered, and every result comes back at low confidence until an excerpt path exists again. - Even at full strength that report could not tell you a cheaper model would have answered acceptably. It models the cheaper model at the actual token counts, though a different model would tokenise differently and may be more or less verbose, and it prices savings at today’s rates rather than the rates in force when the call was made. - The savings report has no dashboard screen. It is an API endpoint over a bounded trace scan, so reading it today means calling it or wiring it into your own reporting. - The kill switch is an admission control. It refuses new work rather than recalling a request already dispatched upstream. - A trace store that cannot make the USD admission atomic has its budgeted traffic refused outright rather than quietly downgraded to completed-spend accounting. - Token Observe cannot bound spend it never sees. A vendor credential used directly, outside the gateway and outside a managed seat, is a discovery problem before it is a budget one. ## Read next - https://tokenobserve.com/platform/model-routing - https://tokenobserve.com/platform/policy-engine - https://tokenobserve.com/platform/flight-recorder ## Questions and answers Q: What happens if a model has no price row? A: It is refused with a 409 before egress, naming the unpriced model, the provider that would have served it and how many further fallbacks are also unpriced. Adding a price row resolves it, as does removing every USD ceiling from an intentionally unbudgeted agent. The alternative was tried and was worse: an unpriced model produced a $0 estimate, which silently disarmed every per-request ceiling. Q: How much should the retrospective savings number be trusted? A: As a pointer, not a figure: read it to decide where to look, and do not quote it. The automatic prompt excerpt it was designed to read has been removed from the gateway, so it now judges a call by token counts and whether tools were offered and returns every result at low confidence. Unpriced calls are skipped rather than assumed free, the scan is bounded to a page of recent traces, and the report ships those assumptions in its own payload. The route to a defensible number is to run the router in shadow mode on your own traffic. The long-form detail on this capability (the anchored sections, the worked policies and the error envelopes) is on the page itself at https://tokenobserve.com/platform/spend-controls.