Use case
How to cap one AI agent's spend at a fixed amount per month
Example: stop one agent from spending more than $500 in a calendar month, without touching any other agent's budget.
One agent-scoped hierarchical budget with a $500 monthly limit in enforce mode. It applies only to that agent's agent_id, every other agent, team, and customer keeps its own separate budget, untouched.
How Spendline does this
Budgets nest: org, team, agent, customer. Scoping the cap at the agent level means it only ever counts spend attributed to that one agent, resets on the calendar month, and is enforced pre-call rather than as an after-the-fact alert. A parent scope (say, the team the agent belongs to) can carry its own separate cap at the same time, and both are checked independently.
Why it matters
A single company-wide budget cannot answer "did agent X specifically overspend"; it can only tell you the whole org went over, after everyone else's spend is already mixed in. A cap scoped to exactly the agent in question is the only way to isolate the problem to its source.
Frequently asked questions
What happens on the first day of the next month?
The monthly scope resets and spend starts accumulating from zero again for that agent, independent of whether the previous month's cap was hit.
Can I set this to alert instead of block?
Not for the block itself. A hierarchical budget has one enforcement switch, strict_mode: on and it blocks with HTTP 402 at the cap, off and calls against it are never blocked. Watching it is a separate mechanism rather than a setting on the budget. Where the hourly burn-rate check is switched on for an account, it reads every hierarchical budget, at any scope including one tied to a single agent, and warns when that budget is on track to run out, regardless of strict_mode; a legacy account-wide budget is outside what it reads. The other lane, the threshold alert fired synchronously on each call, resolves only an org-level or legacy account-wide budget, so it never fires for one scoped to a single agent.
See where this stands in your own setup
This page describes the mechanism. The 5 minute assessment scores your own attribution, enforcement, and reconciliation setup, so you know exactly which of these problems you actually have today.
Run the 5 minute assessment