Skip to main content
A run_budget limits the model calls or model cost of one execution. Set it when starting an Agent Operating Procedure (AOP) through the asynchronous or batch API to stop a run before it admits further model calls beyond its budget.
Loop: next model call, reserve a call slot, check whether the run is within budget, call the model, record actual cost. A call over budget stops the run with reason run_budget.

Each model call reserves a slot and passes a budget check before it runs.

​
Choose limits

Set either field or both. An empty budget is invalid, and additional fields are refused. When you set both limits, either can stop the run. Reaching one does not leave the other available as extra capacity. If the agent definition also supplies a budget, Athena combines the budgets using the lower value for each limit. A request cannot raise a definition’s cap.

​
Start a budgeted execution

The public API supports these execution paths: The API schema names these operations aop.execute_async and aop.execute_batch. Use the matching SDK method if its request type has a run_budget field. Otherwise send the HTTP request directly.
The deprecated POST /api/v0/aop/execute route does not enforce a budget. Its request schema accepts run_budget, but the run starts without it.
  1. Choose an AOP you can run.
  2. Add run_budget beside asset_id and user_inputs in the request body.
  3. Send the request to POST /api/v0/aop/execute-async with your API authentication.
  4. Use the returned thread_id to track execution.
Replace the asset ID and inputs with those of your AOP. Inputs are string values in the request schema. For a batch request, put run_budget at the top level beside runs. Each execution gets its own budget. The amount is not one shared spending pool for the whole batch.

​
Understand call admission

The main run and all its subagents share one execution ledger. A subagent does not receive a fresh copy of the budget. Before each model call, Athena reserves a call slot. Concurrent subagents compete for the same slots, so they cannot each take the last permitted call. Failed provider attempts still consume their reserved slots, including retry and fallback attempts. For a dollar limit, Athena checks accumulated cost before admitting a call. It also estimates the next call using the previous completed call’s cost and refuses a call projected to cross the limit. Cost is recorded after the response reports usage. Actual spend can exceed the dollar limit by the cost of calls already in flight, and their actual cost can differ from the estimate. Treat max_cost_usd as an admission limit rather than an exact final invoice ceiling.

​
Handle a stopped run

When a budget check refuses the next model call, Athena stops the run with a budget-exhausted failure. It records athena_termination_reason=run_budget, and the AOP execution does not report success. Review the work completed so far and the failure message before starting another execution. A new execution can use a larger budget if you choose to continue. A dollar-budgeted run also stops at its next admission if a completed model call cannot be priced. Use a call-count budget when dollar metering is unavailable for the model.

​
Understand unavailable metering

If Athena cannot reach the budget ledger after retries, it refuses the next model call. A budgeted run does not continue by admitting calls without its ledger. An execution with no effective run budget bypasses this budget ledger. Other execution limits still apply. Dry runs started without an explicit budget receive the deployment’s test-run budget.