Batch executions (advanced)

When do you need this? When you want to run the same workflow over many input sets in one go — e.g. generate a hero image for every product in a catalogue. A batch creates and manages many individual executions for you, with a concurrency cap, aggregate progress, and one place to monitor, cancel, or retry. If you only ever run one execution at a time, you can skip this page and use 04-executions.md.

A batch is itself an asynchronous resource (ID prefix bat_…). Creating one fans out into N ordinary executions (run_…), one per input item.

---

1. Create a batch

POST {BASE_URL}/api/v1/batch-executions

Field	Type	Required	Default	Description
workflow	string	✅	–	The workflow to run (wf_…, must be published).
items	array	✅	–	One object per execution. Each maps the workflow’s input keys to values (see §2). At least one item.
version	integer	–	latest	Pin a workflow version.
interface_id	string	–	default	Run every item through a custom interface (03-workflows §5).
name	string	–	–	A display name for the batch.
concurrency_limit	integer	–	5	How many items run simultaneously (1–50).
auto_start	boolean	–	true	Start immediately. Set false to create in a ready state and start later with POST .../start.
stop_on_error	boolean	–	false	Cancel the remaining items the first time an item fails.

curl -s -X POST "$BASE_URL/api/v1/batch-executions" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
    "workflow": "'"$WF"'",
    "name": "Spring catalogue",
    "concurrency_limit": 10,
    "items": [
      { "block_title": "Spring in Bloom",  "product_image_0": "uploads/ws-12/a3/p1.jpg" },
      { "block_title": "Evening Glow",     "product_image_0": "uploads/ws-12/a3/p2.jpg" },
      { "block_title": "Morning Citrus",   "product_image_0": "uploads/ws-12/a3/p3.jpg" }
    ]
  }'

Returns HTTP 202 Accepted with the batch object (see §4), including an input_summary describing how many items were created and whether any were skipped or invalid.

---

2. The items array

Each element of items is one execution’s inputs, expressed as a flat object that maps the workflow’s input keys (the names from the default interface, or the keys from the interface_id you chose) to values:

• Text / number / boolean / JSON inputs → the value directly.
• File inputs (image, video, …) → the asset_path string of a file you uploaded first via 05-assets.md.

"items": [
  { "block_title": "Spring in Bloom", "product_image_0": "uploads/ws-12/a3/p1.jpg" },
  { "block_title": "Evening Glow",    "product_image_0": "uploads/ws-12/a3/p2.jpg" }
]

Note the difference from a single execution. In POST /api/v1/executions, each input is wrapped ({ "value": … } or { "asset_path": … }). In a batch item, the inputs are a plain flat map keyed by the interface field. Discover the exact keys with GET /api/v1/workflows/{id} (03-workflows.md) and validate one item as a single execution first, then scale it out as a batch.

input_summary in the response tells you how the engine interpreted your items:

"input_summary": {
  "items_created": 3,
  "duplicates_skipped": 0,
  "validation_errors": [ { "item_index": 2, "error": "Missing required field 'product_image_0'." } ]
}

---

3. Monitoring, starting, cancelling, retrying

Operation	Endpoint
List batches	GET /api/v1/batch-executions?limit=&starting_after=&status=
Get one batch	GET /api/v1/batch-executions/{id}
List a batch’s items	GET /api/v1/batch-executions/{id}/items?limit=&starting_after=&status=
Start (when auto_start was false)	POST /api/v1/batch-executions/{id}/start
Cancel the batch + pending items	POST /api/v1/batch-executions/{id}/cancel
Retry all failed items	POST /api/v1/batch-executions/{id}/retry-failed

# Poll the batch until it is done
curl -s -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/v1/batch-executions/$BATCH_ID" \
  | jq '{status, progress_percent, completed_items, failed_items, total_items}'

start/cancel/retry-failed return 422 (invalid_state / no_failed_items) when the batch is not in a state that allows the operation.

Inspecting items

GET .../items returns each item with its item_index, status, the inputs you sent, and — once it is running or done — the linked execution ID under execution (a run_…). Use that to drill into a single item’s outputs via the normal execution endpoints (04-executions.md).

{
  "item_index": 0,
  "status": "completed",
  "input_label": "Spring in Bloom",
  "execution": "run_b4c8d3e2…",      // ← fetch this for the item's outputs
  "created_at": "2026-05-27T15:00:00+00:00",
  "completed_at": "2026-05-27T15:00:21+00:00"
}

---

4. The batch object

{
  "id": "bat_9a1c…",
  "workflow": "wf_53fb…",
  "workflow_version": 4,
  "interface_id": null,
  "name": "Spring catalogue",
  "status": "running",            // pending | running | completed | partial_success | failed | cancelled
  "input_mode": "json",
  "total_items": 3,
  "pending_items": 0,
  "running_items": 1,
  "completed_items": 2,
  "failed_items": 0,
  "cancelled_items": 0,
  "progress_percent": 66.7,
  "duplicates_skipped": 0,
  "estimated_credit_cost": 24,
  "actual_credit_cost": 16,
  "concurrency_limit": 10,
  "auto_start": true,
  "stop_on_error": false,
  "created_at": "2026-05-27T15:00:00+00:00",
  "started_at": "2026-05-27T15:00:01+00:00",
  "completed_at": null
}

A batch reaches partial_success when it finishes with some failed items — use retry-failed to re-run just those.

---

5. ZIP export of a batch

Same three-step flow as executions, but the batch ZIP endpoints take the prefixed bat_… ID (unlike the execution ZIP endpoints, which take a raw GUID — see 04-executions §8):

curl -s -X POST -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/v1/batch-executions/$BATCH_ID/zip"
curl -s        -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/v1/batch-executions/$BATCH_ID/zip/status"
curl -sL       -H "Authorization: Bearer $TOKEN" "$BASE_URL/api/v1/batch-executions/$BATCH_ID/zip/$ZIP_ID/download" -o batch.zip

Only available once the batch is terminal; large exports may split into multiple parts.

---

Next: 07-advanced-embed.md (advanced) — embedding a workflow as a widget on your own website.