Cancelling Jobs

Cancel a single job, multiple jobs at once, or an entire batch

PATCH /jobs/{id}/cancel

Cancel job

cURL

curl --request PATCH \
  --url https://api.nexrender.com/api/v2/jobs/{id}/cancel \
  --header 'Authorization: Bearer <token>'

200

[
  {
    "id": "<string>",
    "templateId": "<string>",
    "status": "<string>",
    "progress": 123,
    "stats": {
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "startedAt": "2023-11-07T05:31:56Z",
      "finishedAt": "2023-11-07T05:31:56Z",
      "errorAt": "2023-11-07T05:31:56Z",
      "totalAssets": 123,
      "renderDuration": 123,
      "error": "<string>"
    },
    "outputUrl": "<string>"
  }
]

You can cancel jobs at any point while they are still in a cancellable state - queued or pending. Jobs that are actively rendering (render:dorender) or already in a terminal state (finished, error, manually_cancelled) cannot be cancelled.

Cancellation cascades automatically - if you cancel a parent job, its child jobs are cancelled too. If you cancel a child job, the parent and any sibling jobs that were waiting on it are also cancelled.

​

Cancel a Single Job

Request

curl -X PATCH https://api.nexrender.com/api/v2/jobs/01JTRDF7HCR8QAHYW8GPCP4S9Y/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

The response is an array of all jobs cancelled by the request - including any parent, child, or sibling jobs that were cascaded as a result.

​

Cancel Multiple Jobs

To cancel several jobs in one call, use POST /jobs/cancel with a list of job IDs.

Request

curl -X POST https://api.nexrender.com/api/v2/jobs/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobs": [
      "01JTRDF7HCR8QAHYW8GPCP4S9Y",
      "01JTRGF9KDR4MAHZW9HPCP5T0Z"
    ]
  }'

You can include up to 1,000 job IDs in a single request. Each ID must be unique. If any of the requested jobs are not found, the API returns a 404.

​

Cancel an Entire Batch

To cancel all remaining jobs in a batch, use POST /batches/:id/cancel. See the Batch Jobs page for details.

​

Cancellation Cascade

When a job is cancelled, Nexrender automatically cancels related jobs on a best-effort basis:

Cancelled job	What else gets cancelled
Parent job	All child jobs that are still queued or pending
Child job	The parent job (now unresolvable) and any sibling child jobs waiting alongside it
Batch job	Child jobs belonging to that batch job

All cancelled jobs - both the ones you explicitly requested and any cascaded relatives - are returned in the response array.

​

Cancellable States

Only jobs in the following states can be cancelled:

Status	Cancellable
queued	Yes
pending	Yes
render:dorender	No - actively rendering
finished	No - already complete
error	No - already failed
manually_cancelled	No - already cancelled

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

Path Parameters

id · string · required

Unique job identifier

Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$

Response

200

application/json

Successfully cancelled the job and any related jobs that were also cancellable.

id · string

Unique job identifier used for tracking and API operations

templateId · string | null

Reference to the template used for this job (null if template was not used)

status · string

Current job status (queued, render:dorender, finished, error, etc.). Manually cancelled jobs are normalized to manually_cancelled in v2 responses even though they are stored internally as error.

progress · number<float>

Render progress as a percentage (0.0 to 100.0)

stats · object

Detailed timing and metadata statistics for the job

Show child attributes

outputUrl · string | null

URL to the rendered content