Run a batch
Dispatch every pending row to the renderers after a credit check.
POST /api/batches/{batchId}/runRequires renders:create.
| Name | Type | Required | Description |
|---|---|---|---|
workspace | string | Yes | Workspace slug or id. |
webhooks | boolean | No | Whether this run sends its events to the workspace's webhook endpoints. Omit to keep the batch's setting, which is on. A value you send is saved on the batch, so later runs keep it. |
curl --request POST "https://app.kalpana.one/api/batches/bat_123/run" \
--header "x-api-key: $KALPANA_API_KEY" \
--header "content-type: application/json" \
--data '{"workspace":"acme"}'Response
{
"message": "Dispatched 24 jobs (0 failed)",
"dispatched": 24,
"failed": 0
}Rendering is asynchronous. A successful response only means rows were queued. failed counts rows that could not be queued, for example because their template has been deleted or their data could not be read. Those rows are marked failed at once. Follow progress with Get a batch. Image rows and video rows are routed to their own renderers automatically, so one batch can mix both.
If no rows are pending, the response is {"message":"No pending jobs to process","dispatched":0,"failed":0}. Rows that were already dispatched are not sent twice, so repeating the request is safe.
Running consumes credits. The whole dispatch is rejected with 402 before anything is queued when the organization cannot afford the pending rows, with a message such as Insufficient credits: 48 credit(s) required but only 20 available. Each row's cost is fixed when it is created, and is charged only when the row renders.
Requirements
- A
draftis published as it starts. When it cannot start (not enough credits, say), it stays a draft. Anarchivedbatch is rejected. To add or change jobs of a batch that is already running, use Update a batch, then run it again. - A batch with no creative folder gets one on its first run, named after the batch.
Errors
| Status | Cause |
|---|---|
400 | The batch is archived, or it cannot run. message says why. |
402 | The organization does not have enough credits for the pending rows. |
403 | Your role or key lacks renders:create. |
404 | The batch is not in this workspace. |
Updated 9 Nov 2026