Batch calls

How to run several calculations of one service in a single call: the address, the request and the answer, when a batch is the right tool, and its limits.

What a batch is

A batch call sends a list of input sets to one service and gets all results back in one answer. Each entry is calculated like a single call. One failing entry does not stop the others.

Use a batch when you need many results at once:

• Comparing scenarios, for example the same loan with five interest rates.
• Filling a table or a chart with one calculation per row.
• Processing a list of records in a nightly job.

For one result at a time, the normal call is simpler; see Call a service over the API.

The request

POST https://spreadapi.io/api/v1/services/{serviceId}/batch
Content-Type: application/json

{
  "requests": [
    { "inputs": { "amount": 20000, "rate": 0.04 } },
    { "inputs": { "amount": 20000, "rate": 0.05 } },
    { "inputs": { "amount": 20000, "rate": 0.06 } }
  ]
}

With cURL:

curl -X POST "https://spreadapi.io/api/v1/services/{serviceId}/batch" \
  -H "Content-Type: application/json" \
  -d '{"requests": [{"inputs": {"amount": 20000, "rate": 0.04}}, {"inputs": {"amount": 20000, "rate": 0.05}}]}'

For a token-protected service, put the token into the body as "token", next to "requests":

{
  "token": "YOUR_TOKEN_HERE",
  "requests": [ ... ]
}

The inputs follow the same rules as in a single call: input names are not case-sensitive, required inputs must be present, percentages are decimals.

The answer

{
  "serviceId": "{serviceId}",
  "batch": { "total": 3, "successful": 2, "failed": 1, "executionTime": 48 },
  "results": [
    {
      "index": 0,
      "success": true,
      "outputs": [ { "name": "interest", "title": "Interest", "value": 800 } ],
      "metadata": { "executionTime": 9 }
    },
    {
      "index": 1,
      "success": true,
      "outputs": [ { "name": "interest", "title": "Interest", "value": 1000 } ],
      "metadata": { "executionTime": 7 }
    },
    {
      "index": 2,
      "success": false,
      "error": "Parameter validation failed",
      "message": "1 parameter(s) failed validation"
    }
  ],
  "metadata": { "timestamp": "2026-11-13T09:00:00.000Z", "version": "v1" }
}

• results has one entry per request, in the order you sent them. index is the position in your requests list, starting at 0.
• A successful entry has success: true, outputs and metadata. outputs has the same shape as in a single call; see The API response.
• A failed entry has success: false, error and message.
• batch counts the entries: total, successful, failed, and the time of the whole batch in milliseconds.

The HTTP status is 200 as soon as the batch itself was accepted, even when some entries failed. Always check success per entry.

Limits

• At most 100 requests in one batch, at least 1.
• The whole batch must finish within 30 seconds. Split long jobs into several batches.
• Each successful calculation counts as one call toward the plan's monthly calls. See Call limits.
• Batch calls have a per-minute allowance of their own. For a token-protected service it is 1,000 per minute per token. For a public service it is 60 per minute per caller. A batch is accepted only when the allowance left in the current minute covers the number of its requests; for a public service, keep a batch below 60 requests.
• The batch address exists on spreadapi.io only, not on the short domain.
• The batch answer is JSON only; _format and flatten belong to the single call.

When a batch is refused

These answers concern the whole batch:

A missing or wrong token does not refuse the batch as a whole. Each entry then fails with success: false and the token message in error, for example Invalid token. Meanings and fixes are in the Error reference.

Fresh results

Entries are calculated like single calls, so an entry with inputs that were calculated shortly before may be answered from a stored result. Set "nocache": true at the top of the body for the whole batch, or inside one request for that entry. See Caching and performance.

Batches for AI agents

An AI agent that uses the discovery address of a service has a batch action of its own, with labelled scenarios. See The discovery address.

Related

• Call a service over the API
• Tokens and access
• Limit errors

For developers and agents

Request:

Answer:

An entry whose inputs is not an object fails with error: "CALCULATION_ERROR". The answer carries the headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Reading results by position:

for (const entry of data.results) {
  if (!entry.success) { console.warn(entry.index, entry.error, entry.message); continue; }
  const values = Object.fromEntries(entry.outputs.map((o) => [o.name, o.value]));
}

FAQ

How do I run several calculations in one call?

Send a POST to https://spreadapi.io/api/v1/services/{serviceId}/batch with a body of the form {"requests": [{"inputs": {...}}, {"inputs": {...}}]}. The answer has one result per request.

How many calculations fit into one batch?

At most 100 requests per batch, and the whole batch has to finish within 30 seconds. For a public service keep a batch below 60 requests.

Does a batch count as one call or as many?

As many. Each successful calculation in the batch counts as one call toward the plan's monthly calls.

What happens when one entry of the batch is wrong?

Only that entry fails: it comes back with success: false, error and message. The other entries are calculated normally and the HTTP status stays 200.

Where does the token go in a batch call?

Into the JSON body as "token", next to "requests". The batch address reads the token from the body.

Why does my batch answer 429 although I made few calls?

A batch is accepted only when the per-minute allowance left covers all its requests. Send a smaller batch or wait a minute; details.remaining in the answer says how much is left.

Can I use the short domain for batch calls?

No. Batch calls go to https://spreadapi.io/api/v1/services/{serviceId}/batch. The short domain is for single calls.

How do I match results to my requests?

By index. It is the position of the request in your requests list, starting at 0, and the results come back in the same order.

As an agent, when should I prefer a batch over single calls?

Prefer a batch when the user asks for a comparison or a table of several input sets for the same service. Use single calls for one result or when you need _format or flatten.

Do batch results include the inputs?

No. An entry carries outputs and metadata only; use index to find the inputs you sent.