Run one task over many inputs
run_batchRun one task over many inputs in one call: for repeated runs of the same task, one round trip rather than one per run. Priced the same per item as a single run, with no fee for batching: each item is quoted, reserved and charged on its own, and only a delivered result is charged. Give id and items, 1 to 100 objects of the task's inputs. Every item is checked first: a bad item is refused alone and the others run. Identical items run once and the answer maps back to each position. At most 5 run at once. max_cost_usd caps the whole batch: no item starts if what is charged, plus what is held, plus its own quote could pass it, and items left over answer not_started with nothing charged. A provider that is temporarily unavailable stops only the items it would serve. The answer comes within about 45 seconds: each item in input order has its position, state, rows, charged_usd, error and execution_id, then the totals. Items still going, and rows that did not fit, are read with capability_run_status. An item with rows also has results_page and csv_url: give the person those links instead of writing the rows out again. Sending the same call again the same UTC day answers the same runs with no new charge and starts what did not start; a new idempotency_key runs the items again. A task that is unknown or not ready refuses the whole call, free. NOT for: one run alone, which is run_capability.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"id": "<id>",
"items": "<items>"
},
"name": "run_batch"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | A task id or tool id from capability_search or capability_inspect. One task for the whole batch. | |
| tag | No | Optional: a label for every run in this batch, such as the customer or project it is for: 1 to 64 lowercase letters, digits, dots, dashes or underscores. Activity shows runs and cost by tag. It stays in Ahel and is never sent to a provider. | |
| items | Yes | 1 to 100 objects, each the task's inputs for one run, by name, as run_capability's arguments. | |
| max_items | No | Most rows each item collects, 1-100. Default 10. | |
| max_cost_usd | No | Optional: the most the whole batch may cost, in USD, such as "2.50". Without it the workspace's normal limits apply. | |
| idempotency_key | No | Optional: your own key for this batch, 8 to 200 letters, digits, dots, underscores, colons or hyphens. The same key and item answers the same run with no new charge; a new key runs it again. Left out, the same call the same UTC day is the same batch. |