Sign in

v5

latestOpenAPI 3.0.2raw.githubusercontent.com2026-08-015725.9 KB
tasks

Get Task

Return a single task by ID.

Returns 404 if no task with the given ID exists.

get/api/v1/factory/tasks/{task_id}

Path parameters

task_idinteger required

Response

Successful Response

task_idinteger required
task_typestring required
status'running' | 'completed' | 'failed' | 'cancelled' required

Valid status values for tasks.

Mirrors the CHECK constraint as of migration 1.8.0: status IN ('running', 'completed', 'failed', 'cancelled').

The claim CTE inserts tasks directly as 'running' (the claim is the dispatch; there is no separate queued phase). The three terminal values are written by process_callback and mark_task_failed.

error_messagestring nullable
error_class'transient' | 'permanent' | 'timeout' | 'dispatch_timeout'

Diagnostic class of a failed task.

Mirrors the ck_task_error_class CHECK as of migration 1.8.2: error_class IN ('transient', 'permanent', 'timeout', 'dispatch_timeout'); the column is NULL for non-failure terminals.

  • TRANSIENT: retry-able by the sweeper.
  • PERMANENT: will not improve on retry.
  • TIMEOUT: the coordinator reported an execution timeout — a build that ran and overran its limit.
  • DISPATCH_TIMEOUT: the submit HTTP call to the coordinator itself timed out, so the build's handoff never observably started.

The last two are kept distinct so the read surface shows an execution timeout as timed_out while a submit timeout reads as failed.

created_atstring date-time required
updated_atstring date-time required
started_atstring date-time nullable
completed_atstring date-time nullable