Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.io/llms.txt

Use this file to discover all available pages before exploring further.

​
What you’ll do

Process a folder of product shots through one model in a single call. One callback fires when every item is done.

​
Prerequisites

  • A Runflow API key. Create one.
  • The model you want to run. Pick one from /models.
  • A list of input URLs or asset IDs.

​
Steps

1

Create the batch

POST /v1/models/{model_id}/batches with an array of items, where {model_id} is the slash-delimited provider/model path shown on the model page. Each item is a separate run.
curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/batches \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "input": { "image_url": "https://...01.jpg", "prompt": "white studio" } },
      { "input": { "image_url": "https://...02.jpg", "prompt": "white studio" } },
      { "input": { "image_url": "https://...03.jpg", "prompt": "white studio" } }
    ],
    "callback_url": "https://your-server.com/webhook"
  }'
Response:
{ "id": "01J0...", "status_code": "queued", "items_total": 3 }
2

Poll or wait

Either poll GET /v1/batches/{id} or wait for the callback. Batch records expose status_code; terminal callback payloads expose the same value as status. Batches can also finish as partial_succeeded.
3

Read items

GET /v1/batches/{id}/items returns one entry per input with the resolved run_id, status_code, and outputs.

​
Verify it worked

{
  "id": "batch_01J0...",
  "status_code": "succeeded",
  "items_total": 3,
  "items_succeeded": 3,
  "items_failed": 0
}
items_failed: 0? You’re done.

​
Troubleshooting

SymptomLikely causeFix
Some items fail, others succeedPer-input validation errorRead each failed item’s failure_message.
Whole batch fails fastAuth or quotaCheck the balance.
Callback never arrivesURL not reachableSee Callbacks: local development.

Runs

Single-input lifecycle.

Callbacks

Async result delivery.