From monitoring to strategy: five stages of budget control for agents

If you lead an engineering team that runs agents, pipelines or any other automated system, you already spend money in places nobody approved one call at a time. A coding agent opens a session and burns tokens. A nightly job calls a paid API ten thousand times. A retry loop does what retry loops do.

Most teams meet this problem in the same order. First they want to see what is being spent. Then they want to stop the worst of it. Then they want work that does not fit to wait instead of fail. Then they notice the waste on both sides: work refused while budget sat unused elsewhere, and allowances that reset before anyone spent them. And at the end, the question is no longer “how much did we spend” but “what is this spending for”.

We call this the journey from monitoring to rate-limiting, scheduling, optimisation and strategy. buckette exists to help organisations make it. This post walks through the five stages, with a small example of what each looks like in buckette today. Each stage keeps what the one before it gave you, and you can stop at any of them.

Throughout, a bucket is a budget: a balance on one or more dimensions (tokens, dollars, calls, GPU hours, anything you meter), spent by your code and refilled on a schedule you choose.

1. Monitoring: know what you spend

You cannot set a sensible limit on something you have never measured. So the first stage refuses nothing. It only counts.

Give each agent or workflow its own bucket, and put its dimensions in reporting mode: a reporting dimension never refuses a call, it records it, and its balance is allowed to go negative. Each call reports what it used, and says who used it in its metadata:

POST /buckets/<agent>/consume
{"crAmounts": {"tokens": 12000,
                "usd": 0.18},
 "crMode": {"tag": "Strict"},
 "crMetadata": {"session": "s-42",
                "model": "opus"}}

From there:

  • Monitors in the Console draw dashboards over your buckets: named pages of widgets showing balances, how a budget is shared down a tree of buckets, or anything you write as a template.
  • A breakdown by any key you sent. GET /buckets/<agent>/consume-breakdown?key=model&dimension=usd says how much each model spent this period. Nothing is declared first: session, customer, worktree work the same way.
  • The per-period ledger keeps what each budget used in each period, and a CSV export takes it to a spreadsheet.
  • Alerts without stopping anything. Give a reporting dimension the amount you expect it to use, and a webhook fires when that amount is used up, while the work carries on. You hear about the runaway job while it runs, not at the end of the month.

2. Rate-limiting: put a ceiling on it

Once you know what a workflow normally spends, make its budget a limit. Switch a dimension from reporting to locking, and a call that does not fit is refused. A bucket that refills 200,000 tokens every hour, with nothing carried over, is a rate limit; one that refills once a month is a monthly allowance. Same object, different schedule.

Three tools carry most of the weight here:

  • A bounded budget per run. Split a child bucket off the team’s budget for each agent run, and hand the run a key scoped to that child. The run can spend its share and split it further for its own sub-agents, but it cannot see or touch the parent or its siblings. When the run ends, reclaiming the child returns what it did not use.

    POST /buckets/<team>/split
    {"srAllocation": {"tokens": 50000}}
    
    POST /api-keys
    {"cakreName": "run-42",
     "cakreScopes": ["ScopeConsume",
                     "ScopeRead"],
     "cakreBucketId": "<child>"}
    
  • Holds for calls whose cost you learn afterwards. Reserve an estimate before calling the model, then commit what the call actually used: the difference goes back to the budget. Nobody else can spend the held amount while the call runs.

  • One call, several budgets. A claim pays from several buckets at once, all or nothing: one email takes 1 from the mailbox’s hourly limit and 1 from the campaign’s quota, or from neither.

3. Scheduling: let work wait instead of fail

A refusal is the right answer for a runaway loop. It is the wrong answer for a batch job that would fit in an hour. The third stage turns “no” into “later”.

  • Ask when it would fit. A refused call says when the budget’s own refill schedule would cover it, and you can ask before trying: POST /buckets/<agent>/eta {"etqAmounts": {"tokens": 500}}. The answer is a time, “never” (the request is larger than the budget can ever hold), or “unknown” (the budget has no schedule, for example), so your code can choose between waiting a few seconds, queueing for hours, or giving up.
  • Queue it. A call in Async mode that does not fit is queued and served when the budget refills, with a webhook or a callback when it goes through.
  • Queues with an order. Queued claims are served by priority, oldest first within a priority, so the release pipeline is not stuck behind a thousand backfill jobs.
  • Auctions, when price should decide. The owner of a pool of, say, GPU hours can put an auction on it. At each round, bidders holding a bidding key state a price per unit, the highest prices win, and each winner receives its own child bucket with a key to spend it.

4. Optimisation: waste on both sides

By now the budgets work, and a new kind of question appears. There are two ways to waste a budget, and they pull in opposite directions:

  • Shortfall: work that was refused or kept waiting.
  • Unspent: allowance that reset before anyone used it.

A team that only fights the first sets every limit high and pays for capacity it does not use. A team that only fights the second spends everything early on whatever comes first, and the important work arrives to an empty budget. buckette records both, so you can trade one against the other with numbers instead of guesses:

  • Refused demand is recorded, per budget, for consumes, holds and claims, and the Console has a page for each side: shortfalls, and what went unspent per period.

  • A warning before a reset. A bucket can send a webhook an hour (or a week) before its refill will throw part of the balance away, with the amount at stake, in time to spend it on something useful.

  • Floors between kinds of work. Interactive requests and a batch job can share one monthly allowance without the batch job taking all of it. A floor holds back part of the balance from the lower-value class and releases it as the reset approaches, so what interactive work did not need is still spent by the end of the period:

    PUT /buckets/<allowance>/class-config
    {"classes": {
       "interactive": {},
       "batch": {"tokens": {
         "floor": 400000,
         "release": "linear"}}},
     "default_class": "batch"}
    

    buckette can suggest the floors from your own history, and replay the past periods with them, before you set anything.

  • A policy from your record. Run a dimension in reporting mode for a few periods, then ask buckette to propose a refill policy that would have covered that demand, replayed over the same periods: what it would have served, refused and discarded.

Planned, not built: a packing assistant that takes a set of queued work items, each carrying the value you attach to it, and proposes which to run within the budgets you have.

5. Strategy: decide what the spending is for

The last stage is not a new feature so much as a different question. Once spend is measured, bounded, scheduled and tuned, the budgets themselves become a statement of priorities: how much of next month goes to the customer-facing agent, how much to internal tooling, how much to experiments.

What buckette gives you for that conversation today:

  • The record to argue from. The per-period ledger, the breakdowns by team, model or customer, and the refused-demand totals say what was spent on what, and what was asked for and not served.
  • Forecasts. A refused or queued consume carries an estimate of when the budget’s refills will cover it. The warning before a reset is a forecast of what will expire. A pacing read shows how a budget is being spent over its period, slice by slice, so you can see a month that will run out on the 20th while it is still the 10th.
  • Alerts where you already look. Threshold and reset warnings arrive as webhooks, which the notifier can forward to Slack, Discord or PagerDuty, or which your own on-call tooling can receive.
  • Value next to demand. A claim can carry the value you assign to the work, in whatever units you name. buckette records it on the claim and on every event it writes, refusals included, so you can later ask which refused work was worth the most.

Planned, not built: an optimiser that uses those values to decide what to serve first, and advice on unspent budget that ranks the refused work by its value. The value field ships first, and records only, so that the history is there when the optimiser arrives.

Where to start

Start at the first stage, even if you are sure you need the third. A week of reporting-mode buckets tells you where the limits should be, and every later stage reads from that record. The getting started page sets up a first budget in a few minutes, and the guide for agents has every route mentioned here.

If your team is somewhere on this path and something is missing, write to hello@buckette.co. We would like to hear which stage you are at.