Workers

Worker resources combine durable registration data with recent heartbeats and in-memory statistics. Capabilities are normalized into records so operators can inspect large FFmpeg installations without losing their type.

List workers

Returns worker capacity, connectivity, resources, and capabilities.

GET

/api/v1/operations/workers200

Parameters

Name	In	Type	Description
`state`	query	`WorkerState`	Filter by STARTING, IDLE, BUSY, DRAINING, or OFFLINE.
`connectivity`	query	`WorkerConnectivity`	Filter by ONLINE, SUSPECTED, or OFFLINE.
`limit`	query	`integer (1..100)`	Maximum records to return.Default: `50`
`offset`	query	`integer (0..100000)`	Records to skip.Default: `0`

Request

curl --header 'authorization: Bearer ADMIN_ACCESS_TOKEN' \
  'http://localhost:4400/api/v1/operations/workers?connectivity=ONLINE&limit=25'

Response excerpt

{
  "items": [{
    "id": "d3058e48-8b28-4ef1-8c80-45f83eb6f5f1",
    "instanceId": "c82f5bd9-a2ff-4ec1-93d9-34bdfd506c37",
    "hostname": "encode-node-01",
    "version": "0.0.1",
    "ffmpegVersion": "7.1",
    "state": "IDLE",
    "connectivity": "ONLINE",
    "capacity": { "activeJobs": 0, "maxConcurrentJobs": 2 },
    "resources": { "cpuCores": 16, "cpuPercent": 8.4, "gpuPercent": null },
    "capabilities": [{ "kind": "encoder", "name": "libx264", "metadata": null }],
    "connectedAt": "2026-09-10T08:30:00.000Z",
    "lastSeenAt": "2026-09-10T09:00:00.000Z"
  }],
  "total": 1,
  "limit": 25,
  "offset": 0
}

Possible errors

400A filter or pagination value is invalid.

Get a worker

Returns worker details, current telemetry, and active attempts.

GET

/api/v1/operations/workers/:workerId200

Parameters

Name	In	Type	Description
`workerId`required	path	`UUID`	Stable Worker UUID.

Request

curl --header 'authorization: Bearer ADMIN_ACCESS_TOKEN' http://localhost:4400/api/v1/operations/workers/d3058e48-8b28-4ef1-8c80-45f83eb6f5f1

Response excerpt

{
  "id": "d3058e48-8b28-4ef1-8c80-45f83eb6f5f1",
  "hostname": "encode-node-01",
  "state": "BUSY",
  "connectivity": "ONLINE",
  "liveStats": { "cpuPercent": 8.4, "memoryUsedBytes": 1835008000 },
  "activeAttempts": [],
  "completedCount": 142,
  "failedCount": 3
}

Possible errors

400workerId is not a UUID.

404The worker does not exist.

Drain a worker

Stops new assignments while allowing active jobs to finish.

POST

/api/v1/operations/workers/:workerId/drain202

Parameters

Name	In	Type	Description
`workerId`required	path	`UUID`	Worker UUID to drain.

Drain state is sticky across subsequent worker heartbeats.

Request

curl --request POST --header 'authorization: Bearer ADMIN_ACCESS_TOKEN' http://localhost:4400/api/v1/operations/workers/d3058e48-8b28-4ef1-8c80-45f83eb6f5f1/drain

Response excerpt

{
  "id": "d3058e48-8b28-4ef1-8c80-45f83eb6f5f1",
  "state": "DRAINING",
  "connectivity": "ONLINE",
  "capacity": { "activeJobs": 1, "maxConcurrentJobs": 2 }
}

Possible errors

400workerId is not a UUID.

404The worker does not exist.

409The worker is offline and cannot be drained.

State versus connectivity

state describes operational intent and capacity: STARTING, IDLE, BUSY, DRAINING, or OFFLINE. connectivity describes heartbeat freshness: ONLINE, SUSPECTED, or OFFLINE.

A Worker can become suspected before its state is finally made offline. Thresholds are controlled by the Manager’s Worker connectivity configuration.

Capability records

Each capability has a kind, name, and optional metadata. Current kinds are encoder, decoder, filter, hwaccel, and gpu. The Admin detail screen groups these categories and collapses long lists.