> ## Documentation Index
> Fetch the complete documentation index at: https://resources.athenaintel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution run budgets

> Cap model calls and model cost for asynchronous AOP executions and batch runs

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.](https://mintcdn.com/athenaintelligence-e46bc9d3/6ueVSVCwufwDQRFe/images/diagrams/run-budget.webp?fit=max\&auto=format\&n=6ueVSVCwufwDQRFe\&q=85\&s=e9ea4756e2590404d00899d239330f3e)

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

## Choose limits

| Field | Accepted value | Limit |
| - | - | - |
| `max_model_calls` | Integer of at least 1 | Model-call attempts across the main run and its subagents. |
| `max_cost_usd` | Number greater than 0 | Accumulated model provider cost in USD, calculated using Athena's model pricing. |

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:

| API call | Budget scope |
| - | - |
| `POST /api/v0/aop/execute-async` | One execution. |
| `POST /api/v0/aop/execute-batch` | The same limits applied separately to each run in the request. |

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.

> [!WARNING]
>
> 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.

```json theme={null}
{
  "asset_id": "asset_9249292-d118-42d3-95b4-00eccfe0754f",
  "user_inputs": {
    "task": "Summarize the available records"
  },
  "run_budget": {
    "max_model_calls": 40,
    "max_cost_usd": 10
  }
}
```

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.

## Related

* [AOPs](https://resources.athenaintel.com/docs/pillars/applications/aops.md)
* [SDK quickstart](https://resources.athenaintel.com/docs/developer-integrations/sdk-quickstart.md)
* [API overview](https://resources.athenaintel.com/docs/developer-integrations/api-reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.