Many calculations in one call (batch)
Updated 2026-11-16
An agent connected to your account can calculate up to 100 sets of inputs in one call. This page explains when that helps, how a batch is sent and answered, and how it is counted.
When a batch helps
Whenever there is more than one calculation:
- A list: "Work out the premium for these 40 customers from the CSV." One call instead of 40.
- Options to compare: "What does it cost with 5, 10 and 15 years?" One call, one answer to present side by side.
- Checking a draft: before a service is published, the agent tests it against every case it knows from the spreadsheet in one go, for example ten rows with the results the spreadsheet shows.
For the agent, one call is faster than many, keeps its context short, and leaves nothing half done when a single row has a wrong value.
How to ask for it
You do not need to know the details: ask your AI in your own words, for example "calculate this for every row of the list" or "compare these three options". An agent connected to SpreadAPI uses a batch on its own; its instructions tell it to.
Batches work with both actions that calculate:
| Action | Calculates on | Counted |
|---|---|---|
run_service | the published service | each scenario as one call of the month |
test_service | the draft | not counted |
For agents: sending a batch
Send scenarios instead of inputs: a list of up to 100 entries, each with its own inputs and an optional label. Send exactly one of inputs and scenarios.
{
"service_id": "ab12_mwdimeoyhzzge",
"scenarios": [
{ "label": "5 years", "inputs": { "loan_amount": 300000, "fixed_period": 5 } },
{ "label": "10 years", "inputs": { "loan_amount": 300000, "fixed_period": 10 } },
{ "label": "15 years", "inputs": { "loan_amount": 300000, "fixed_period": 15 } }
],
"outputs": ["monthly_payment", "interest_rate"]
}labelis your name for the scenario, for example a customer number. Without one, a scenario is named by its position: "1", "2", and so on.- An input a scenario leaves out takes its default, or the value of the workbook. Nothing carries over from one scenario to the next.
outputsis optional and returns only the outputs named. It works for a single calculation too and keeps a large batch short. An unknown name is refused before anything is calculated; the answer lists the outputs the service has.
For agents: the answer
{
"ok": true,
"action": "run_service",
"service_id": "ab12_mwdimeoyhzzge",
"scenarios": [
{ "label": "5 years", "ok": true, "inputs": { "loan_amount": 300000, "fixed_period": 5 },
"outputs": { "monthly_payment": 1480.0, "interest_rate": 0.0352 }, "display": { "interest_rate": "3.52%" } },
{ "label": "10 years", "ok": true, "inputs": { "loan_amount": 300000, "fixed_period": 10 },
"outputs": { "monthly_payment": 1427.5, "interest_rate": 0.0371 }, "display": { "interest_rate": "3.71%" } },
{ "label": "15 years", "ok": false,
"error": { "code": "invalid_values", "message": "…", "problems": [ { "at": "inputs.fixed_period", "code": "invalid", "message": "…" } ] } }
],
"summary": { "total": 3, "ok": 2, "failed": 1 }
}scenarioscome back in the order sent, each with itslabelandok.- A scenario with
"ok": truehasinputs,outputsanddisplay, exactly like a single calculation. - A scenario with
"ok": falsehas anerrorwithcode,messageandproblems. The other scenarios are calculated all the same; the call as a whole is"ok": true. summarycounts the scenarios:total,ok,failed.- The whole call fails only when it cannot be calculated: an unknown output name (
invalid_input), a data source that cannot be read (data_source_unavailable), or not enough calls left (call_limit_reached, see below).
Take every number from the answer. When a scenario failed, tell your user which one and why, using its message and problems; fix its values and send only that scenario again.
How a batch is counted
- `run_service`: every scenario is one call of the service and counts towards the account's calls of the month, a refused scenario too. In the usage overview each one appears as a call over the AI channel.
- Before anything is calculated, the batch is checked against the calls the account has left this month. If it does not fit as a whole, nothing is calculated and nothing is counted. The answer is
call_limit_reachedwith the number of calls left, for example: "This batch needs 40 calls, but the account has 12 left this month." Send a smaller batch, or tell your user. - `test_service` counts nothing, single or batch.
- The rate limit of the connection (120 calls a minute) counts the batch as one call.
Limits
- At most 100 scenarios per call. More rows: send several batches one after the other.
- For lists of hundreds or thousands of rows on a schedule, use the REST batch address of the published service in a workflow instead; see Batch calls.
Batches elsewhere
- The MCP address of one service has its own tool for comparing options,
spreadapi_batch, with 2 to 20 scenarios; see The MCP address of a service. - The REST API takes up to 100 calculations in one request at
/api/v1/services/{serviceId}/batch; see Batch calls.
FAQ
Can my AI calculate a whole list at once?
Yes. An agent connected to your account sends up to 100 rows in one call and gets one answer with a result per row. For longer lists it sends several batches.
What happens when one row has a wrong value?
Only that row fails. Its entry in the answer says why; all other rows are calculated. The agent can fix the row and send it again on its own.
Does a batch use more of my monthly calls?
Each calculation counts once, whether it is sent alone or in a batch. Ten scenarios in one call are ten calls, the same as ten single calls. Tests on a draft are not counted.
What if my calls are almost used up?
A batch that needs more calls than are left is not calculated at all, so it never stops halfway. The agent is told how many calls are left and can send a smaller batch or tell you.
Can the agent test a draft with many cases before publishing?
Yes. test_service takes the same scenarios, up to 100, and counts nothing. This is the best way to check that a service calculates exactly like the spreadsheet before it is published.
As an agent, should I use run_service with scenarios or spreadapi_batch?
Through the account connection (/mcp), use scenarios on run_service or test_service. spreadapi_batch belongs to the MCP address of one published service, which others use without an account connection.