Run batches
Run one Addon on many items with the same settings, for example one catalog
photo per product. Starting needs runs:create, following needs
runs:read, and retrying, redoing or cancelling needs runs:manage. Each item's run
pays its price in credits when it succeeds.
Before you start
Set GHOSTPULL_URL and GHOSTPULL_API_KEY as in the
quickstart, and upload the photos.
This guide runs catalog-photo on two uploaded photos whose asset keys are
in photos.json, an array such as
[{"key":"accounts/…/versions/…","mediaType":"image/png"}]. The bash/zsh
and fish examples also need jq.
1. Start the batch
Call startOrchestratorBatch
with the Addon's ID, the inputs every item shares and up to 50 items,
each with its own inputs. As for a single run, an API key must send
maxCredits, the most each item's run may cost, and a new unique
idempotencyKey for each batch you intend:
- bash / zsh
- fish
- PowerShell
jq '{addonId:"catalog-photo",inputs:{},items:map({inputs:{image:.}}),maxCredits:10,idempotencyKey:"spring-catalog-2026-10-30"}' photos.json > batch-request.json
curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/orchestrator/batches" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data-binary @batch-request.json --output batch.json
BATCH_ID=$(jq -r .batchId batch.json)
jq '{addonId:"catalog-photo",inputs:{},items:map({inputs:{image:.}}),maxCredits:10,idempotencyKey:"spring-catalog-2026-10-30"}' photos.json > batch-request.json
curl --fail-with-body -X POST "$GHOSTPULL_URL/api/v1/orchestrator/batches" \
-H "x-api-key: $GHOSTPULL_API_KEY" -H "Content-Type: application/json" \
--data-binary @batch-request.json --output batch.json
set BATCH_ID (jq -r .batchId batch.json)
$photos = Get-Content photos.json | ConvertFrom-Json
$body = @{
addonId = "catalog-photo"
inputs = @{}
items = @($photos | ForEach-Object { @{ inputs = @{ image = $_ } } })
maxCredits = 10
idempotencyKey = "spring-catalog-2026-10-30"
} | ConvertTo-Json -Compress -Depth 6
$body | Set-Content -Encoding utf8NoBOM batch-request.json
curl.exe --fail-with-body -X POST "$env:GHOSTPULL_URL/api/v1/orchestrator/batches" `
-H "x-api-key: $env:GHOSTPULL_API_KEY" -H "Content-Type: application/json" `
--data-binary "@batch-request.json" --output batch.json
$env:BATCH_ID = (Get-Content batch.json | ConvertFrom-Json).batchId
The call answers 202 at once with the batchId. Every item is checked
before anything starts: a refused item names its details.index, and a
batch the account cannot pay in total is refused with details.required
and details.available. Nothing starts and nothing is reserved then.
At most 5 of the batch's runs go at once; the next item starts when one ends. A batch started with an API key uses each Addon's current production version.
2. Follow the batch
Call getOrchestratorBatch
every 20 seconds or so while its status is RUNNING, or follow it with
streamOrchestratorBatch,
which works like a run's stream:
- bash / zsh
- fish
- PowerShell
curl --fail-with-body "$GHOSTPULL_URL/api/v1/orchestrator/batches/$BATCH_ID" \
-H "x-api-key: $GHOSTPULL_API_KEY"
curl --fail-with-body "$GHOSTPULL_URL/api/v1/orchestrator/batches/$BATCH_ID" \
-H "x-api-key: $GHOSTPULL_API_KEY"
curl.exe --fail-with-body "$env:GHOSTPULL_URL/api/v1/orchestrator/batches/$env:BATCH_ID" `
-H "x-api-key: $env:GHOSTPULL_API_KEY"
Each item has its index in your items, its status and, once it
succeeded, its outputs. A failed item has error and a message you can
show. The batch is ENDED once no item waits or runs.
listOrchestratorBatches
lists the account's batches, newest first.
3. Retry failed items
Call retryOrchestratorBatch
with {} to start every FAILED and TIMED_OUT item again, or name items
by index, such as {"items":[3]}. Each retried item starts as a new run in
the same place and pays its price again when it succeeds. An item whose own
inputs caused its error has retriable: false and is left out: replace its
input and start it in a new batch.
4. Redo finished items with a note
For an Addon whose ui.redo in listAddons
lists choices, call redoOrchestratorBatch
to make SUCCEEDED items again with a note of what to fix, such as
{"items":[{"index":3,"choices":["complete"],"text":"show the whole bottle"}]}.
Each redone item starts as a new run with the inputs the batch started
with, and pays its price again when it succeeds.
While the new run goes, the item keeps showing its earlier result as
previousRunId; once it succeeded, the item shows the new one. To keep the
earlier result instead, call
setOrchestratorBatchItemVersion
with its runId. Choosing costs nothing.
5. Cancel the batch
Call cancelOrchestratorBatch.
Waiting items never start, running runs are stopped, and finished items
keep their results. A cancelled batch cannot be retried.
When the key is revoked
A batch keeps the API key that started it, also when another key or a
person retries it. Once that key is revoked, expires or loses
runs:create, the batch starts no more items: its waiting items end as FAILED
with the error Batch.KeyRevoked, and its running runs finish as usual. The
batch can no longer be retried or redone (409 orchestrator.batch_key_revoked); start
the remaining items as a new batch with the new key.