# Batches

Run many jobs with one call. You set how many may run at the same time and, optionally, a price limit for the whole batch. Each job has its own result; a failed job does not stop the others.

## Submit a batch

**Python**

```
from wbxsandbox import run_batch, batch_input

batch = run_batch(
    [{"command": "python worker.py 1"}, {"command": "python worker.py 2"},
     {"command": "python merge.py", "depends_on": [0, 1],
      "inputs": [batch_input(0, "output/part.csv", "p1.csv"), batch_input(1, "output/part.csv", "p2.csv")]}],
    defaults={"template": "base", "save_artifacts": True},
    max_concurrency=10, max_total_cost="2.00", idempotency_key="nightly-2026-11-08")

print(batch.wait().summary()["status"])          # completed / partial / failed
open("report.csv", "w").write(batch.report_csv())
```

**curl**

```
curl -s -X POST https://sandbox.wbx.cz/v1/batches -H "Authorization: Bearer YOUR_API_KEY" -H "Idempotency-Key: nightly-2026-11-08" \
  -d '{"defaults": {"template": "base", "timeout_s": 600, "artifacts": ["output/"]},
       "jobs": [{"command": "python worker.py 1"}, {"command": "python worker.py 2"},
                {"command": "python merge.py", "depends_on": [0, 1],
                 "inputs": [{"from_index": 0, "name": "output/part.csv", "as": "p1.csv"},
                            {"from_index": 1, "name": "output/part.csv", "as": "p2.csv"}]}],
       "max_concurrency": 10, "max_total_cost": "2.00"}'

curl -s https://sandbox.wbx.cz/v1/batches/BATCH_ID -H "Authorization: Bearer YOUR_API_KEY"
curl -s "https://sandbox.wbx.cz/v1/batches/BATCH_ID/report?format=csv" -H "Authorization: Bearer YOUR_API_KEY" -o report.csv
```

## Endpoints

| Endpoint | What it does |
| --- | --- |
| POST /v1/batches | `jobs` (1–1000, each with the fields of `POST /v1/jobs` plus `depends_on`), `defaults`, `max_concurrency` (1–100, default 10), `max_total_cost` (billing currency; `max_total_cost_eur` for EUR accounts), `name`, `idempotency_key`, `webhook_url`. The batch is accepted as a whole or not at all. |
| GET /v1/batches | Your batches, newest first: `since` (RFC 3339), `limit` (max 100) and `cursor` (from `next_cursor`). |
| GET /v1/batches/{id} | Summary: counts by state, cost, cost per completed job, durations (p50/p95), errors by code, first failed jobs, next step. |
| GET /v1/batches/{id}/report | The summary plus one row per job; `?format=csv` for a spreadsheet. |
| POST /v1/batches/{id}/cancel | Cancel the jobs that have not finished yet. |

## Dependencies and status

A job with `depends_on` starts only after those jobs completed successfully; if one of them fails, the job is cancelled with `dependency_failed`. Inside a batch, `inputs` with `from_index` gives a job the result files of another job of the same batch – see [Passing files between jobs](https://sandbox.wbx.cz/docs/jobs/inputs.md).

The batch status is `completed`, `partial` (some jobs failed), `failed` or `cancelled`.

> **More than 100 at the same time?** One batch runs at most 100 jobs at once. For more parallel work, submit several batches – each has its own concurrency and price limit.

Source: https://sandbox.wbx.cz/docs/jobs/batches
