---
title: "Get Build"
method: GET
path: "/api/v1/factory/builds/{build_id}"
tags: ["builds"]
---

# Get Build

`GET /api/v1/factory/builds/{build_id}`

## Request

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

Return a single build by ID with its task sub-object and outputs.

## Path parameters

- `build_id` integer, required

## Response `200`

Successful Response

- BuildDetailResponse: A single build, with the outputs of the derivation it published.
  - `build_id` integer, required
  - `status` 'pending' | 'running' | 'completed' | 'failed' | 'timed_out' | 'cancelled', required: Effective status of a build, derived server-side and never stored. A dispatched build's task lifecycle is authoritative, with timed_out reconstructed from a failed task whose error class is 'timeout'; a build cancelled before dispatch is cancelled; an undispatched, uncancelled build is pending. These six values are exactly what the derivation can emit; emittable, filterable, and the whole vocabulary are the same set. The member order here is the documentation order.
  - `source_repo_url` string, required
  - `source_commit_sha` string, required
  - `nixpkgs_revision` string, required
  - `system` string, required
  - `attr_path` string, required
  - `build_type` string, required
  - `catalog_name` string, required
  - `exit_code` integer, nullable
  - `created_at` string, date-time, required
  - `task` 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
  - `trigger` BuildTrigger: What scheduled a build.
    - `kind` string
    - `stabilities` string[]: The stabilities that named this build's nixpkgs revision when the build was scheduled. Empty when none did, as for a manifest build, which does not build against the revision. Not the revision's current stabilities, which can move after scheduling.
  - `published_package` PublishedPackage: The catalog package a build published.
    - `name` string, required: The published derivation's name, such as `hello-2.12.1`.
    - `version` string, nullable, required: The published derivation's version, null when it has none.
    - `source_rev_count` integer, required: The revision count of the source page the package was built from. One part of the build's coordinate: builds of the same source revision with different locked inputs or base page share it.
    - `description` string, nullable, required: The published derivation's description, null when it has none.
    - `license` string, nullable, required: The published derivation's license as the catalog records it, such as `MIT` or `[ MIT, Apache-2.0 ]`; null when it has none.
  - `outputs` BuildOutput[]: Every output of the derivation the build published, with its recorded sizes. Empty when no published package is linked to the build.
    - `name` string, required
    - `store_path` string, required
    - `nar_size` integer, nullable: Size in bytes of the store path's NAR. Null when no size has been recorded: the publish has not finished uploading, failed to record it, or went to a store that records no sizes. On a base-catalog store path, also null when the crawler has not recorded the path or cache.nixos.org has no NAR for it.
    - `closure_size` integer, nullable: Total size in bytes of the NARs in the store path's closure. Null when none has been recorded. The base-catalog crawler records none, so a base-catalog store path has one only when a publish recorded it as part of a closure.
    - `is_default` boolean, required: Whether the output is installed by default: it is named in the derivation's `outputs_to_install`.

## Other responses

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

## Changes

- **2026-10-22** `a0a0401010b7`: 2 info
  - added the optional property `outputs` to the response with the `200` status
  - added the optional property `published_package` to the response with the `200` status
- **2026-10-01** `76701e311542`: 1 info
  - added the optional property `trigger` to the response with the `200` status
- **2026-08-27** `f17e891a3eeb`: 6 breaking, 4 warning, 1 info
  - the `task` response's property type changed from `object` to no type for status `200`
  - removed the required property `task/created_at` from the response with the `200` status
  - removed the required property `task/status` from the response with the `200` status
  - removed the required property `task/task_id` from the response with the `200` status
  - …7 more
- **2026-07-28** `ffc271c8797c`: 14 warning
  - added the new `cancelled` enum value to the `status` response property for the response status `200`
  - added the new `cancelled` enum value to the `task/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 `completed` enum value to the `task/status` response property for the response status `200`
  - …10 more
- **2026-06-23** `7c0e206cb685`: 1 info
  - added the required property `status` to the response with the `200` status

[Operation history](https://skmtc.dev/flox/apis/flox-factory-service/changes/api/v1/factory/builds/:build_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)