Skip to main content
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.
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.
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 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.
  • 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 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.