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

# List Builds

`GET /api/v1/factory/builds`

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: 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_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `started_at` string, date-time, nullable
      - `completed_at` string, date-time, nullable
  - `total` integer, required
  - `page` integer, required
  - `page_size` integer, required

## Other responses

- `422` — Unprocessable Entity

---

[API](https://skmtc.net/flox/apis/flox-factory-service.md) · [All operations](https://skmtc.net/flox/apis/flox-factory-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/flox/flox-factory-service/versions/ffc271c8797c/schema)