Skip to main content
A budget caps how much a scope can spend on LLM calls. ForceAI tracks the cost of every request in the spend logs and rejects a request once the applicable budget is exceeded. Budgets attach directly to orgs, teams, users, and virtual keys; agents inherit theirs from the key they run under, and access groups do not carry a budget at all

​
Where a budget can live

There is no per-access-group budget. To budget a group of keys, put them in a team and set the team’s max_budget, or point them all at one shared Budget object

​
How enforcement works

Every request arrives on a virtual key, and that key belongs to a user, a team, and an org. ForceAI checks the request against every level that has a budget, and the tightest limit that is already exceeded blocks it. So a key can be under its own cap yet still be rejected because its team’s monthly cap is used up. The error is explicit, for example:
Three modifiers apply on any level:
  • budget_duration sets a reset window (1h, 30d, 1mo, and so on). Spend resets at budget_reset_at, which gives you recurring budgets
  • soft_budget is an alert threshold, not a block. You get notified but requests keep flowing
  • model_max_budget sets per-model caps within one scope, for example {"gpt-4": 10, "claude-haiku-4-5": 100}
Enforcement is near-real-time, not instantaneous. Spend is flushed to the database on an interval, so a burst of requests can briefly run past the cap before the next request is blocked. Budgets are a spend guardrail, not a hard transaction limit

​
The Budgets page

The dashboard Budgets page manages reusable Budget objects: a named budget with a max, an optional duration, and optional per-model caps. Create one there, then attach it to an org (or reference it from a key) instead of retyping the same limits everywhere

​
Set a budget

1

On a virtual key

Set a max budget and duration when you create or edit the key. By API:
2

On a team (the group budget)

Every key created in that team draws down the one team budget
3

On an org

Teams and keys created under the org all count toward it
4

On an agent

An agent uses a virtual key, so budget the key it runs under. Create the key with the agent as owner (Virtual Keys -> Create Key -> Owned By: Agent) and set its max_budget, or create a service-account key with a budget and attach it to the agent

​
Verify a budget blocks

Set a tiny budget, spend past it, and the next request is rejected. Against a team with max_budget: 0.0002:
Once cumulative spend crosses the cap you get Budget has been exceeded! Team=... Current cost: ... Max budget: 0.0002, and because the budget is on the team, a brand-new key in that team is blocked immediately too
Use a very small max_budget and allow a few seconds between requests so spend flushes; otherwise a rapid burst may run slightly past the cap before the block engages