---
title: "List Builds"
method: GET
path: "/api/v1/factory/builds"
tags: ["builds"]
---

# List Builds

`GET /api/v1/factory/builds`

## Request

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

Return a paginated list of builds, newest first.

The ``status`` filter matches builds by an effective status derived
from the build's lifecycle (never stored), drawn from a six-value
vocabulary:

- ``pending``: accepted but not yet dispatched to a builder.
- ``running``: dispatched and building.
- ``completed``: finished successfully.
- ``failed``: finished unsuccessfully. Excludes timed-out builds,
  which match ``timed_out``.
- ``timed_out``: terminated for exceeding its time budget.
- ``cancelled``: cancelled, whether before or after dispatch.

These six values are both the filter vocabulary and the response
vocabulary: a timed-out build matches ``?status=timed_out`` and
reports ``status: "timed_out"`` in the response body.

Filters:

- ``status``: match one or more effective-status values.
- ``system``: match system names exactly. A name outside the
  server's system vocabulary returns 422 naming the accepted
  values, which are the systems this deployment's catalog holds
  and so may differ between deployments.
- ``attr_path``: match attr_path by prefix.
- ``source_commit_sha``: match source commit SHA by prefix.
- ``since``: return builds created at or after this time. An ISO
  8601 timestamp carrying a UTC offset, e.g.
  ``2026-07-17T08:30:00Z``.

Filters combine with AND across parameters and OR within a repeated
one: ``?status=running&status=failed`` matches either status, and
adding ``&system=x86_64-linux`` further requires that system. Each
repeated parameter accepts at most 50 values.

``cursor`` and ``sort`` are reserved for future use and have no
effect in v1; results are always ordered newest-first.

## Query parameters

- `status` EffectiveBuildStatus[], nullable: Filter by effective status; repeatable, matched as OR. One of pending, running, completed, failed, timed_out, cancelled.
- `system` string[], nullable: Filter by system, matched exactly; repeatable, matched as OR. Values must be non-empty, and a value outside the server's system vocabulary returns 422 naming the accepted values.
- `attr_path` string[], nullable: Filter by attr_path prefix; repeatable, matched as OR. Values must be non-empty.
- `source_commit_sha` string[], nullable: Filter by source commit SHA prefix; repeatable, matched as OR. Values must be non-empty.
- `since` string, date-time, nullable: Return builds created at or after this time (inclusive). An ISO 8601 timestamp carrying a UTC offset, e.g. '2026-07-17T08:30:00Z'.
- `page` integer
- `page_size` integer
- `cursor` string, nullable: Reserved for future use; not implemented in v1 (results are always ordered newest-first).
- `sort` string, nullable: Reserved for future use; not implemented in v1 (results are always ordered newest-first).

## Response `200`

Successful Response

- BuildListResponse: Paginated list of builds.
  - `builds` BuildResponse[], required
    - `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.
  - `total` integer, required
  - `page` integer, required
  - `page_size` integer, required

## Other responses

- `422`: Unprocessable Entity

## Changes

- **2026-10-22** `a0a0401010b7`: 1 info
  - added the optional property `builds/items/published_package` to the response with the `200` status
- **2026-10-01** `76701e311542`: 1 info
  - added the optional property `builds/items/trigger` to the response with the `200` status
- **2026-08-27** `f17e891a3eeb`: 6 breaking, 4 warning, 1 info
  - the `builds/items/task` response's property type changed from `object` to no type for status `200`
  - removed the required property `builds/items/task/created_at` from the response with the `200` status
  - removed the required property `builds/items/task/status` from the response with the `200` status
  - removed the required property `builds/items/task/task_id` from the response with the `200` status
  - …7 more
- **2026-07-28** `ffc271c8797c`: 15 warning, 7 info
  - for the `query` request parameter `page`, the max was set to `10737418.00`
  - added the new `cancelled` enum value to the `builds/items/status` response property for the response status `200`
  - added the new `cancelled` enum value to the `builds/items/task/status` response property for the response status `200`
  - added the new `completed` enum value to the `builds/items/status` response property for the response status `200`
  - …18 more
- **2026-06-23** `7c0e206cb685`: 1 info
  - added the required property `builds/items/status` to the response with the `200` status

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