Batch Jobs - Nexrender Cloud Documentation

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

{
  "batchId": "<string>",
  "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>"
    }
  ]
}

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

{
  "batchId": "<string>",
  "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

Field	Type	Description
`batchId`	string	Unique identifier for this batch
`status`	string	`"created"` if all jobs succeeded, `"partial"` if some failed, `"error"` if all failed
`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"
    }
  ]
}

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

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.

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

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

Tracking Render Jobs Cancelling Jobs

Documentation Index

​Submit a Batch

​Batch Creation Response

​Partial Success Example

​Check Batch Status

​Batch Status Values

​Batch Stats Fields

​Cancel a Batch

​Cancellation Response Status Values

​When to Use Batches

Rendering Basics

Nested Jobs

Authorizations

Body

Response

Submit a Batch

Batch Creation Response

Partial Success Example

Check Batch Status

Batch Status Values

Batch Stats Fields

Cancel a Batch

Cancellation Response Status Values

When to Use Batches