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

> ## Agent Instructions
> Peel builds APIs from a URL and a task. Use only the REST routes under https://api.peel.sh and the hosted MCP server at https://api.peel.sh/mcp. Authenticate with the X-API-Key header, or send the same key as Authorization: Bearer. Errors carry code, message, retryable, retry, docs_url and details; branch on code. The peel CLI and the open-source SDK are not published; do not run npm install peel, which is an unrelated package. The keyless routes need no key and no session: the GET /public/marketplace routes, POST /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call and https://api.peel.sh/mcp/keyless. Account routes take a key or a signed-in session and answer 401 without one. These take only a session from peel.sh and refuse a key: GET /v1/accounts, POST /v1/accounts/join, POST /v1/accounts/{account_id}/leave, POST /v1/team/invites, GET /v1/connected-apps, DELETE /v1/connected-apps/{client_id}, PUT /v1/logins, DELETE /v1/logins, GET /v1/logins/code and the /account/billing routes. Every route with its schemas is in https://docs.peel.sh/openapi.json. Use the exact route, field and error-code names shown in these pages, and read the API Reference tab for request and response schemas.

# Batches

> Run one read endpoint on up to 100 inputs in one call and get every result back in order.

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.

```bash theme={null}
curl https://api.peel.sh/v1/apis/$API_ID/endpoints/search_flights:batch \
  -H "X-API-Key: $PEEL_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: fares-2026-11" \
  -d '{
    "defaults": {"from": "SFO", "to": "JFK"},
    "items": [
      {"key": "nov-20", "input": {"date": "2026-11-20"}},
      {"key": "nov-21", "input": {"date": "2026-11-21"}}
    ]
  }'
```

For a plain list without keys, send `inputs` instead of `items`. Add a [`shape`](https://docs.peel.sh/features/shapes) to reshape every item's result. Marketplace endpoints take the same body at `/v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:batch`.

```json theme={null}
{
  "counts": { "succeeded": 2, "failed": 0, "not_run": 0 },
  "credits_charged": 2,
  "items": [
    { "key": "nov-20", "status": "success", "status_code": 200, "data": { "fares": [] }, "error": null, "error_code": null },
    { "key": "nov-21", "status": "success", "status_code": 200, "data": { "fares": [] }, "error": null, "error_code": null }
  ]
}
```

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:

| Code | Status | Why |
| - | - | - |
| `invalid_request` | 400 | No items, more than 100, or a malformed body |
| `batch_not_allowed` | 409 | The endpoint signs in, needs a signed-in session, or takes an action. Call those one at a time. |
| `endpoint_not_found` | 404 | No such API or endpoint |
| `api_not_ready` | 409 | The API is still building |

## 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.


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