api reference · tcp · queries

Ask about a job, change nothing.

Read jobs by internal or custom ID, their state, result and progress, list them with filters and pagination, and count them by state or priority.

Part of the TCP protocol reference, which describes the framing, authentication, pipelining and response format that every command on this page uses.

Two more read-only commands are documented next to the limits they describe: GetQueueLimits and GetDeduplicationJobId.

Query Commands

GetJob

Retrieve a job by its internal ID.

Request:

{ cmd: 'GetJob', id: string }

Response:

{ ok: true, job: Job }

Returns an error if the job is not found.

---

GetState

Get the current state of a job.

Request:

{ cmd: 'GetState', id: string }

Response:

{ ok: true, id: string, state: string }

Possible states: waiting, prioritized, delayed, active, waiting-children, completed, failed, or unknown (job not found).

---

GetResult

Get the stored result of a completed job.

Request:

{ cmd: 'GetResult', id: string }

Response:

{ ok: true, id: string, result: any }

The result field is the value passed via ACK. It may be null or undefined if no result was stored or if the result has been evicted from the LRU cache.

---

GetJobs

List jobs with filtering and pagination.

Request:

{
  cmd: 'GetJobs',
  queue: string,
  state?: JobState | JobState[],  // e.g. 'waiting', 'delayed', 'active', 'completed', 'failed', or an array
  limit?: number,        // Max results (default: 100)
  offset?: number,       // Skip N results (default: 0)
  asc?: boolean          // createdAt/id order (default: true)
}

Response:

{ ok: true, jobs: Job[] }

Ordering is applied before pagination. Send the same asc value on every request when traversing multiple offset pages.

---

GetJobCounts

Get job counts grouped by state for a specific queue.

Request:

{ cmd: 'GetJobCounts', queue: string }

Response:

{
  ok: true,
  counts: {
    waiting: number,
    prioritized: number,
    delayed: number,
    active: number,
    completed: number,
    failed: number,
    'waiting-children': number,
    paused: number
  }
}

When the queue is paused, ready jobs are reported under paused instead of waiting/prioritized (BullMQ semantics).

---

GetCountsPerPriority

Get job counts grouped by priority level for a specific queue.

Request:

{ cmd: 'GetCountsPerPriority', queue: string }

Response:

{ ok: true, queue: string, counts: Record<number, number> }

---

GetJobByCustomId

Look up a job by its custom ID (the jobId field from PUSH).

Request:

{ cmd: 'GetJobByCustomId', customId: string }

Response:

{ ok: true, job: Job }

Returns an error if no job with that custom ID exists.

---

Count

Get the number of queued jobs in a queue (waiting, prioritized, and delayed; active, completed, and failed jobs are not counted).

Request:

{ cmd: 'Count', queue: string }

Response:

{ ok: true, count: number }

---

GetProgress

Get the progress of an active job.

Request:

{ cmd: 'GetProgress', id: string }

Response:

{ ok: true, progress: number, message: string | null }

---

GetChildrenValues

Get the return values from all child jobs of a parent job. Used with FlowProducer workflows to retrieve results from completed children.

Request:

{ cmd: 'GetChildrenValues', id: string }

Response:

{ ok: true, data: { values: Record<string, any> } }

Keys are <queue>:<childId>, or the bare childId when the child job no longer exists. Returns an empty values object if the job has no children; a lookup failure returns the normal { ok: false, error } response.