Skip to main content
A batch runs one endpoint on 1 to 100 inputs, such as a search for twenty dates, and answers once every item has ended. Each item is its own call: a bad input or a failed run affects only that item.

Run a batch

Send the inputs to :batch beside :call. Give each item an input and an optional key of your own; Peel echoes the key on its result. Fields in defaults apply to every item, and an item’s own fields win.
For a plain list without keys, send inputs instead of items. Add a shape to reshape every item’s result. Marketplace endpoints take the same body at /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:batch.
Each item carries the same fields as a single call’s answer, in the order you sent them.

How items run

  • Four items run at once. Each time the site answers 429, 418 or a JSON body saying 429, the batch halves how many run at once, down to one. Peel never retries an item on its own.
  • An input that does not match the endpoint’s schema fails its own item with input_invalid and is not charged.
  • Items that have not started 60 seconds after the batch began end with status: "not_run" and batch_timed_out. If you close the connection, items not yet started end with batch_cancelled.
  • With an Idempotency-Key, item i runs with the key <key>:<i>, so repeating the batch never charges an item twice.

What it costs

Each successful item is charged as one call of that endpoint, on every plan. Failed and unstarted items cost nothing. credits_charged is the total.

What a batch refuses

The whole batch is refused before anything runs when:

From an MCP client

The Peel MCP lists call_endpoint_batch for your APIs and call_marketplace_endpoint_batch for marketplace APIs. Both take items, optional defaults and an optional idempotency_key, and answer with the same body.