Skip to main content

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:

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)

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:

curl --fail-with-body "$GHOSTPULL_URL/api/v1/orchestrator/batches/$BATCH_ID" \
-H "x-api-key: $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.

Next​