Skip to main content
POST
Create batch of jobs

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')