Skip to main content
POST
Create batch of jobs
A batch lets you submit up to 1,000 render jobs in one POST /batches request. Each job in the batch follows the same schema as a single job. The API returns a batchId you can use to track progress and cancel the whole group at once. Batches support partial success - if some jobs fail validation, the rest still proceed. The response tells you exactly which succeeded and which failed, with per-job error details.

Submit a Batch

Each entry in jobs includes an index that maps back to its position in the original request array, so you can correlate results even when some fail.

Batch Creation Response

Partial Success Example

If a job fails validation, its entry appears in errors with an index matching its position in the original request. Successfully created jobs proceed normally.

Retry a Batch Safely

A network error or timeout can leave you unsure whether a batch was created. To make a batch safe to resend, choose its batchId yourself: send a ULID you generate in the request. Sending the batch again with the same batchId creates only the jobs that are not in it yet, so no job is rendered twice. Give each job a batchItemId (up to 255 characters) so a retry can tell the jobs apart. Jobs without one are matched by their position in jobs, so if you leave it out, keep the order the same on every retry.
A retry answers 200 instead of 201: The jobs array lists every job in the batch, with each index pointing to its position in the request you just sent. Retries are recognised for 30 days, while the batch’s jobs are kept. A retry after that, or a request without a batchId, creates a new batch.
Don’t send two requests with the same batchId at the same time: if they overlap on the server, both can create jobs. A timeout on your side does not mean the server stopped working on the batch. After a timeout, poll GET /batches/:batchId until it stops changing, then retry.

Retry Errors

Check Batch Status

Poll GET /batches/:batchId to see aggregate progress across all jobs in the batch.

Batch Status Values

Batch Stats Fields

Cancel a Batch

Cancel all remaining jobs in a batch with a single call. Jobs that have already finished are not affected.

Cancellation Response Status Values

Cancellation cascades to child jobs - if a batch job has nested children, they are cancelled too.

When to Use Batches

  • Rendering personalised videos for a large user list (event invites, product variants, certificates)
  • Processing a bulk export where you want to submit all jobs upfront and track completion as a group
  • Any workflow that needs atomic cancellation of many jobs at once
Each job in a batch is a full, independent job - it can include nested job assets, upload configuration, webhooks, and all other job options.

Rendering Basics

Learn the full job payload structure and asset types

Nested Jobs

Use nested job assets to render child compositions first

Authorizations

Authorization
string
header
required

Bearer token authentication using API tokens for team-based access control.

You can generate your own API token at: https://app.nexrender.com/settings/api-tokens

Body

application/json

Configuration for creating a batch of render jobs in a single request (1 to 1000 jobs)

jobs
object[]
required

Array of job configurations to create as a batch. Each item follows the same schema as a single job creation request, plus an optional batchItemId string (at most 255 characters) that identifies the job within the batch when it is retried. Items without one are matched by their position.

Required array length: 1 - 1000 elements
batchId
string

Optional client-chosen ULID that makes the request safe to retry. Sending a batch again with the same batchId creates only the jobs that are not in it yet: the response is 200 with status 'replayed' when nothing was missing, or 'partial' when the missing jobs were created. Retries are recognised for 30 days, while the batch's jobs are kept. Requests with the same batchId must not run at the same time: two that overlap on the server can both create jobs. A timeout on your side does not mean the server stopped processing, so after a timeout wait until GET /batches/{id} stops changing before retrying. Without it the API generates one, and a retry creates a new batch.

Pattern: ^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$

Response

A retry with an existing batchId. Status 'replayed' when every job already existed, 'partial' when the missing jobs were created now.

Response after creating a batch of jobs, including per-job results and any errors

batchId
string
required

Unique batch identifier in ULID format for tracking the entire batch

status
enum<string>
required

'created' if all jobs succeeded, 'partial' if some failed or a retry created only the missing jobs, 'error' if all failed, 'replayed' if a retry with the same batchId found every job already created

Available options:
created,
partial,
error,
replayed
totalJobs
integer
required

Total number of jobs in the batch request

successCount
integer
required

Number of successfully created jobs

jobs
object[]
required

Array of successfully created job details

error
string

Present on 409 and 503 responses: why the batch could not be completed

errorCode
string

Present on 409 and 503 responses, for example BATCH_ALREADY_PARTIAL or BATCH_RETRYABLE

errors
object[]

Array of errors for failed jobs (only present when status is 'partial' or 'error')