Execute a Batch of Agent Operating Procedures | Athena

curl -X POST https://api.athenaintel.com/api/v0/aop/execute-batch \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "runs": [
    {
      "client_ref": "row-1",
      "user_inputs": {
        "company": "Acme Corp"
      }
    },
    {
      "client_ref": "row-2",
      "user_inputs": {
        "company": "Globex"
      }
    }
  ],
  "asset_id": "asset_9249292-d118-42d3-95b4-00eccfe0754f",
  "run_budget": {
    "max_cost_usd": 30,
    "max_model_calls": 80
  }
}'

{
  "failed": 0,
  "launched": 2,
  "runs": [
    {
      "index": 0,
      "aop_asset_id": "asset_9249292-d118-42d3-95b4-00eccfe0754f",
      "client_ref": "row-1",
      "thread_id": "thread_12345-6789-abcd-efgh"
    },
    {
      "index": 1,
      "aop_asset_id": "asset_9249292-d118-42d3-95b4-00eccfe0754f",
      "client_ref": "row-2",
      "thread_id": "thread_22345-6789-abcd-efgh"
    }
  ],
  "batch_id": "batch_1f3c1b9e-7f7d-4c2c-9d5e-2b1f0a9c8d7e"
}

Start many Agent Operating Procedure (AOP) runs under one batch handle. Each run is queued exactly like POST /aop/execute-async; the response returns a batch_id so the caller polls GET /aop/batches/{batch_id} once per batch instead of once per thread. Pass the batch_id back to append more runs to the same batch. Runs are launched independently: a run that fails to launch is reported with an error and does not stop the others. Runs are idempotent within a batch: a run whose idempotency_key (or, when omitted, client_ref) was already launched into the same batch with the same parameters is not started again; its original outcome is replayed with deduplicated: true.

Start many Agent Operating Procedure (AOP) runs under one batch handle. Each run is queued exactly like `POST /aop/execute-async`; the response returns a `batch_id` so the caller polls `GET /aop/batches/{batch_id}` once per batch instead of once per thread. Pass the `batch_id` back to append more runs to the same batch. Runs are launched independently: a run that fails to launch is reported with an error and does not stop the others. Runs are idempotent within a batch: a run whose `idempotency_key` (or, when omitted, `client_ref`) was already launched into the same batch with the same parameters is not started again; its original outcome is replayed with `deduplicated: true`.

Authentication

X-API-KEYstring

API Key authentication via header

Request

This endpoint expects an object.

runslist of objectsRequired

Runs to launch (1-100 per request). Launch more into the same batch by repeating the call with the returned batch_id.

asset_idstring or nullOptional

Default AOP asset ID for runs that omit their own asset_id

batch_idstring or nullOptionalformat: "^batch_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"

Existing batch to append these runs to (returned by a previous execute-batch call). Omit to start a new batch.

dry_runbooleanOptionalDefaults to false

Execute every run in dry-run mode: side-effectful tool calls are validated and captured instead of executed.

run_budgetobject or nullOptional

Per-run spend cap (max_model_calls / max_cost_usd) applied to every run in the request.

Response

Batch accepted; see per-run outcomes

failedinteger

Runs in this request that could not be launched

launchedinteger

Runs accepted and queued in this request

runslist of objects

Per-run launch outcome, in request order

batch_idstring or nullOptional

Batch handle. Poll GET /aop/batches/{batch_id} for the whole batch instead of every thread, and pass it back to POST /aop/execute-batch to append more runs. Null when a new batch launched no runs: there is nothing to poll or append to, so no handle is issued.

deduplicatedintegerOptionalDefaults to 0

Runs in this request that replayed an earlier launch (same idempotency_key / client_ref in this batch) instead of starting

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

422

Unprocessable Entity Error

500

Internal Server Error