---
title: "Get Task"
method: GET
path: "/api/v1/factory/tasks/{task_id}"
tags: ["tasks"]
---

# Get Task

`GET /api/v1/factory/tasks/{task_id}`

## Request

- The document declares no server URL.
- Auth: one of:
  - HTTP bearer
  - HTTP basic

Return a single task by ID.

Returns 404 if no task with the given ID exists.

## Path parameters

- `task_id` integer, required

## Response `200`

Successful Response

- TaskResponse: Generic task lifecycle — same shape for all operation types. The status field carries the task vocabulary — the persisted lifecycle words, distinct from the derived effective vocabulary on BuildResponse.status. The task sub-object reports the stored footprint the top-level status is derived from: a timed-out build's task still reads status='failed' + error_class='timeout' while the build-level status reads 'timed_out'.
  - `task_id` integer, required
  - `task_type` string, 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_message` string, 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: says nothing of the build itself, such as a build the coordinator lost or gave no status for. - 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_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable

## Other responses

- `404`: Not Found
- `422`: Unprocessable Entity

## Changes

- **2026-08-27** `f17e891a3eeb`: 1 breaking, 5 info
  - the `error_class` response's property type changed from `string` to no type for status `200`
  - added `#/components/schemas/TaskErrorClass` to the `error_class` response property `allOf` list for the response status `200`
  - removed the `dispatch_timeout` enum value from the `error_class` response property for the response status `200`
  - removed the `permanent` enum value from the `error_class` response property for the response status `200`
  - …2 more
- **2026-07-28** `ffc271c8797c`: 8 warning
  - added the new `cancelled` enum value to the `status` response property for the response status `200`
  - added the new `completed` enum value to the `status` response property for the response status `200`
  - added the new `dispatch_timeout` enum value to the `error_class` response property for the response status `200`
  - added the new `failed` enum value to the `status` response property for the response status `200`
  - …4 more

[Operation history](https://skmtc.dev/flox/apis/flox-factory-service/changes/api/v1/factory/tasks/:task_id/get.md)

---

[API](https://skmtc.dev/flox/apis/flox-factory-service.md) - [All operations](https://skmtc.dev/flox/apis/flox-factory-service/llms.txt) - [OpenAPI document](https://skmtc.dev/flox/apis/flox-factory-service/revisions/a0a0401010b7?raw)