Queue Jobs

List jobs

GET /queue/jobs

Auth: API Key required

Query parameters

number

default:"50"

Maximum number of jobs to return (pagination).

number

default:"0"

Number of jobs to skip (pagination offset).

offset is ignored whenever status is set. The filtered path calls getJobsByStatus(status, limit), which takes no offset, so paginating a filtered list re-returns the same first page. offset is echoed back in the response either way.

string

Filter by job status. One of: pending, processing, completed, error, cancelled.

Response

This endpoint serves database rows as they are stored. Field names are snake_case, not camelCase, and timestamps are epoch milliseconds, not ISO 8601 strings.

{
  "jobs": [
    {
      "id": "job_abc123",
      "file_path": "videos/clip.mp4",
      "params_json": "{\"width\":640}",
      "cache_path": "cache/w_640/videos/clip.mp4",
      "status": "completed",
      "priority": 2,
      "progress": 100,
      "error": null,
      "retry_count": 0,
      "max_retries": 3,
      "created_at": 1773567000000,
      "started_at": 1773568200000,
      "completed_at": 1773568305000
    }
  ],
  "limit": 50,
  "offset": 0,
  "count": 1
}

array

Show Job object

string

Unique job identifier.

string

Storage path of the video being processed.

string

The transformation parameters the job was queued with, as a JSON string. Together with file_path this is the key a job is looked up by.

string

Where the finished variant is written.

string

pending · processing · completed · error · cancelled

number

Processing priority, lower runs first. Thumbnails are queued at 1 and transformations at 2.

number

Progress percentage, 0 to 100.

string

Error message when status is error, null otherwise.

number

Attempts made so far.

number

Attempt ceiling, from VIDEO_JOB_RETRY_MAX.

number

Epoch milliseconds when the job was queued.

number

Epoch milliseconds when processing started, null while pending.

number

Epoch milliseconds when processing finished, null until then.

number

Number of jobs in this response, not the total matching the filter.

Video Status returns the same jobs in a converted shape: camelCase keys and ISO 8601 timestamps. The two endpoints do not agree on field names by design, one serves rows and the other serves a view model.

Example

# List all failed jobs
curl "http://localhost:3000/queue/jobs?status=error&limit=20" \
  -H "Authorization: Bearer <api_key>"

Retry job

POST /queue/jobs/{jobId}/retry

Re-queues a failed job for processing. Auth: API Key required

Path parameters

string

required

ID of the job to retry. Must have error status.

Response

{
  "success": true,
  "message": "Job scheduled for retry"
}

Status codes: 200 success · 400 job not in error state · 500 error

Example

curl -X POST http://localhost:3000/queue/jobs/job_abc123/retry \
  -H "Authorization: Bearer <api_key>"

Cancel job

POST /queue/jobs/{jobId}/cancel

Cancels a pending job before it starts processing. Auth: API Key required

Path parameters

string

required

ID of the job to cancel. Must have pending status.

Response

{
  "success": true,
  "message": "Job cancelled"
}

Status codes: 200 success · 400 job not pending · 500 error

Example

curl -X POST http://localhost:3000/queue/jobs/job_abc123/cancel \
  -H "Authorization: Bearer <api_key>"

Delete job

DELETE /queue/jobs/{jobId}

Permanently removes a job record from the queue. Auth: API Key required

Path parameters

string

required

ID of the job to delete.

Response

{
  "success": true,
  "message": "Job deleted"
}

Status codes: 200 success · 400 failed · 500 error

Example

curl -X DELETE http://localhost:3000/queue/jobs/job_abc123 \
  -H "Authorization: Bearer <api_key>"

Queue Statistics

Aggregate counts per status.

Queue Events (SSE)

Real-time progress updates.

Video Status

Check processing status by file path.

Overview

Media

Files

Storage

Cache

Video Processing

API Keys

System

List jobs

Query parameters

Response

Example

Retry job

Path parameters

Response

Example

Cancel job

Path parameters

Response

Example

Delete job

Path parameters

Response

Example

Queue Statistics

Queue Events (SSE)

Video Status

​List jobs

​Query parameters

​Response

​Example

​Retry job

​Path parameters

​Response

​Example

​Cancel job

​Path parameters

​Response

​Example

​Delete job

​Path parameters

​Response

​Example

​Related

Queue Statistics

Queue Events (SSE)

Video Status

List jobs

Query parameters

Response

Example

Retry job

Path parameters

Response

Example

Cancel job

Path parameters

Response

Example

Delete job

Path parameters

Response

Example

Related