Batch Jobs

Submit up to 1,000 render jobs in a single API request and track them as a group

POST /batches

Create batch of jobs

cURL

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": {
        "frames": 1,
        "codec": "<string>",
        "engine": "ae2026",
        "multiFrame": true,
        "lottie": {}
      },
      "upload": {
        "prefix": "<string>",
        "outputUrl": "<string>",
        "provider": "s3"
      }
    }
  ]
}
'

201

{
  "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

Request

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

Field	Type	Description
batchId	string	Unique identifier for this batch
status	string	"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 found every job already created
totalJobs	integer	Total number of jobs in the request
successCount	integer	Number of successfully created jobs
jobs	array	Details for each successfully created job
errors	array	Details 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"
    }
  ]
}

​

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.

{
  "batchId": "01JZ8Q4V6T2M9X3K5R7B1N0C8D",
  "jobs": [
    {
      "batchItemId": "invite-alice",
      "template": { "id": "01JTGM9GCR71JV7EJYDF45QAFD", "composition": "main" },
      "assets": [{ "type": "text", "layerName": "name", "value": "Alice Johnson" }]
    },
    {
      "batchItemId": "invite-bob",
      "template": { "id": "01JTGM9GCR71JV7EJYDF45QAFD", "composition": "main" },
      "assets": [{ "type": "text", "layerName": "name", "value": "Bob Williams" }]
    }
  ]
}

A retry answers 200 instead of 201:

Status	Meaning
replayed	Every job was already in the batch. Nothing new was created.
partial	The jobs that were missing have been created now.

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

HTTP	errorCode	Meaning
400	INVALID_BATCH_ID	batchId is not a valid ULID.
400	INVALID_BATCH_ITEM_ID	A batchItemId is longer than 255 characters.
400	DUPLICATE_BATCH_ITEM_ID	Two jobs in the request have the same identifier.
409	BATCH_ALREADY_PARTIAL	The jobs already in the batch could not be matched with the request. Check GET /batches/:batchId before sending again.
503	BATCH_RETRYABLE	The service was briefly unavailable part-way through. The jobs created so far are listed. Wait for the Retry-After header’s number of seconds, then retry with the same batchId to create the rest.

​

Check Batch Status

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

Request

curl -X GET https://api.nexrender.com/api/v2/batches/01BATCH_ID_HERE \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Batch Status Values

Status	Meaning
processing	At least one job is still running or queued
finished	All jobs have completed (some may have errored)
error	All jobs failed

​

Batch Stats Fields

Field	Description
total	Total jobs in the batch
finished	Jobs that completed successfully
error	Jobs that failed
pending	Jobs 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.

Request

curl -X POST https://api.nexrender.com/api/v2/batches/01BATCH_ID_HERE/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

​

Cancellation Response Status Values

Status	Meaning
cancelled	Every cancellable job was cancelled
partial	Some jobs were cancelled, others were already in a terminal state
unchanged	No 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/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.

Required array length: 1 - 1000 elements

Show child attributes

Response

201

application/json

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

Show child attributes

errors · object[]

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

Show child attributes