Skip to main content
POST
/
batches
Create batch of jobs
curl --request POST \
  --url https://api.nexrender.com/api/v2/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jobs": [
    {
      "template": {
        "id": "<string>",
        "src": "<string>",
        "composition": "<string>"
      },
      "preview": false,
      "fonts": [],
      "assets": [],
      "settings": {
        "type": "video",
        "frames": 1,
        "quality": "draft",
        "codec": "<string>",
        "engine": "ae2026"
      },
      "upload": {
        "prefix": "<string>",
        "outputUrl": "<string>",
        "provider": "s3"
      }
    }
  ]
}
'
{
  "batchId": "<string>",
  "status": "created",
  "totalJobs": 123,
  "successCount": 123,
  "jobs": [
    {
      "index": 123,
      "id": "<string>",
      "status": "<string>",
      "outputUrl": "<string>",
      "children": [
        {
          "id": "<string>",
          "status": "<string>",
          "outputUrl": "<string>",
          "missingFonts": [
            "<string>"
          ]
        }
      ],
      "missingFonts": [
        "<string>"
      ]
    }
  ],
  "errors": [
    {
      "index": 123,
      "error": "<string>",
      "errorCode": "<string>"
    }
  ]
}
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

curl -X POST https://api.nexrender.com/api/v2/batches \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      {
        "template": {
          "id": "01JTGM9GCR71JV7EJYDF45QAFD",
          "composition": "main"
        },
        "assets": [
          {
            "type": "text",
            "layerName": "name",
            "value": "Alice Johnson"
          }
        ],
        "webhook": {
          "url": "https://yourdomain.com/webhooks/render-complete"
        }
      },
      {
        "template": {
          "id": "01JTGM9GCR71JV7EJYDF45QAFD",
          "composition": "main"
        },
        "assets": [
          {
            "type": "text",
            "layerName": "name",
            "value": "Bob Williams"
          }
        ],
        "webhook": {
          "url": "https://yourdomain.com/webhooks/render-complete"
        }
      }
    ]
  }'
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

FieldTypeDescription
batchIdstringUnique identifier for this batch
statusstring"created" if all jobs succeeded, "partial" if some failed, "error" if all failed
totalJobsintegerTotal number of jobs in the request
successCountintegerNumber of successfully created jobs
jobsarrayDetails for each successfully created job
errorsarrayDetails for each failed job (only present when status is "partial" or "error")

​
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. 
{
  "batchId": "01BATCH_ID_HERE",
  "status": "partial",
  "totalJobs": 3,
  "successCount": 2,
  "jobs": [
    {
      "index": 0,
      "id": "01JOB_A_ID",
      "status": "queued",
      "outputUrl": "https://nx1-outputs-eu.nexrender.com/.../job-a.mp4"
    },
    {
      "index": 2,
      "id": "01JOB_C_ID",
      "status": "queued",
      "outputUrl": "https://nx1-outputs-eu.nexrender.com/.../job-c.mp4"
    }
  ],
  "errors": [
    {
      "index": 1,
      "error": "Template not found",
      "errorCode": "TEMPLATE_NOT_FOUND"
    }
  ]
}

​
Check Batch Status

Poll GET /batches/:batchId to see aggregate progress across all jobs in the batch. 
curl -X GET https://api.nexrender.com/api/v2/batches/01BATCH_ID_HERE \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Batch Status Values

StatusMeaning
processingAt least one job is still running or queued
finishedAll jobs have completed (some may have errored)
errorAll jobs failed

​
Batch Stats Fields

FieldDescription
totalTotal jobs in the batch
finishedJobs that completed successfully
errorJobs that failed
pendingJobs still queued or rendering

​
Cancel a Batch

Cancel all remaining jobs in a batch with a single call. Jobs that have already finished are not affected. 
curl -X POST https://api.nexrender.com/api/v2/batches/01BATCH_ID_HERE/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Cancellation Response Status Values

StatusMeaning
cancelledEvery cancellable job was cancelled
partialSome jobs were cancelled, others were already in a terminal state
unchangedNo jobs were in a cancellable state
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/team/settings

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.

Required array length: 1 - 1000 elements

Response

Batch created successfully. Check 'status' field: 'created' means all jobs succeeded, 'partial' means some failed (see 'errors' array).

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, 'error' if all failed

Available options:
created,
partial,
error
​
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

​
errors
object[]

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