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

# Run many inputs at once

> Run one read-only tool on up to 100 inputs in one call, as a batch, and read every item's result.

> [!NOTE]
>
> **Batches are available only on Business accounts for now.**

A batch runs one read-only tool on 1 to 100 inputs in one call, such as Google Flights searches for twenty dates. Each input runs as its own run, in parallel, and the whole batch counts as at most one tool run.

## Start a batch

Send the tool and its inputs to `POST /v1/runs/read-only/batch`, or to `POST /v1/integrations/{id}/tools/{tool_id}/runs/batch` for an integration's tool. Give each item an optional `key` of your own to match results to inputs, and put fields every item shares in `defaults`; an item's own fields win.

```bash theme={null}
curl https://api.pomerado.ai/v1/runs/read-only/batch \
  -H "Authorization: Bearer $POMERADO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fares-2026-11" \
  -d '{"tool_id":"tool_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190","defaults":{"from":"SFO","to":"JFK"},"items":[{"key":"nov-20","input":{"date":"2026-11-20"}},{"key":"nov-21","input":{"date":"2026-11-21"}}]}'
```

The call answers at once with the batch: its `batch_` ID, `status`, `counts` and its items in the order you sent them. Send `inputs` instead of `items` for a plain list of inputs without keys.

## Follow it to the end

Read `GET /v1/batches/{id}` until `status` is `completed` or `cancelled`. While it runs, the answer's `Retry-After` header says when to read again.

```bash theme={null}
curl "https://api.pomerado.ai/v1/batches/batch_7c1e9a2b4d6f48e0a3b5c7d9e1f20304?include_result=false" \
  -H "Authorization: Bearer $POMERADO_API_KEY"
```

Each item has its `status` and its run's `job`, the same job `GET /v1/jobs/{id}` returns, or an `error` saying why it never ran. The batch is `completed` once every item's job has ended. An item whose tool is being repaired keeps the batch running until that repair ends. Results are handed out once, as a run's are: read with `include_result=false` while you wait, then once without it to take them. An answer stops adding results after about 1 MiB; `more_results: true` means read again for the rest.

## Items are independent

A batch isn't all or nothing. An input that doesn't match the tool's `input_schema` never runs: its item answers `invalid_input` in its place, and the others still run. Each item's run succeeds, fails or is repaired on its own. Only a refusal of the call itself, such as a write tool (`tool_not_read_only`), an account without Business (`business_account_required`) or a spent allowance (`quota_exceeded`), refuses the whole batch before anything runs.

## Stop a batch

`POST /v1/batches/{id}/cancel` ends the items not yet started with `batch_cancelled`; items already running finish and keep their results.

## From an MCP client

Each [integration MCP](https://docs.pomerado.ai/guides/integration-mcps/overview.md) lists a batch copy of every read tool that needs no login, named after the tool with `_batch` at the end. It takes `items`, each with its `input` and optional `key`, and an optional `idempotency_key`, and waits for the batch as a run call waits for its job; if the batch is still running, call it again with `batch_id`. On the Pomerado MCP, find `runs.create_read_only_batch` and `runs.get_batch` with `search_pomerado_api` and call them with `call_read_only_pomerado_api`.

> [accordion] Details
>
> * A batch takes 1 to 100 items, of one tool whose effect is `read`.
> * A batch doesn't take a saved login yet: a body with `login_id` is refused with `invalid_request`.
> * Items still waiting to start 15 minutes after the batch began end with `batch_timed_out` and never run.
> * A batch can be read for 7 days after it ends.
> * The whole batch counts as one tool run against your [allowance](https://docs.pomerado.ai/guides/plans-and-limits.md) if any of its items ends with a result, however many items it has.
> * Pomerado paces the items to what the website answers, and slows down when it starts refusing requests. It never retries an item on its own, except to repair a broken tool.
> * Repeating the call with the same `Idempotency-Key` returns the same batch.
> * A batch is started from the API or MCP, not the Dashboard. Each item's run is listed among your runs.


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