---
title: "List builds"
method: GET
path: "/builds"
---

# List builds

`GET /builds`

## Query parameters

- `tags` Tags — User-defined key-value tags.

## Response `200`

List of builds

- Build[]
  - `id` string, required — Build job identifier
  - `status` 'queued' | 'building' | 'pushing' | 'ready' | 'failed' | 'cancelled', required — Build job status
  - `tags` Tags — User-defined key-value tags.
  - `queue_position` integer, nullable — Position in build queue (only when status is queued)
  - `image_digest` string, nullable — Digest of built image (only when status is ready)
  - `image_ref` string, nullable — Full image reference (only when status is ready)
  - `error` string, nullable — Error message (only when status is failed)
  - `provenance` BuildProvenance
    - `base_image_digest` string — Pinned base image digest used
    - `source_hash` string — SHA256 hash of source tarball
    - `lockfile_hashes` object — Map of lockfile names to SHA256 hashes
    - `buildkit_version` string — BuildKit version used
    - `timestamp` string, date-time — Build completion timestamp
  - `created_at` string, date-time, required — Build creation timestamp
  - `started_at` string, date-time, nullable — Build start timestamp
  - `completed_at` string, date-time, nullable — Build completion timestamp
  - `duration_ms` integer, nullable — Build duration in milliseconds
  - `builder_instance_id` string, nullable — Instance ID of the builder VM (for debugging)

## Other responses

- `401` — Unauthorized
- `500` — Internal server error

## Changes

- **2026-03-09** `d3b8f05f7a0f` — 2 warning, 2 info
  - deleted the `query` request parameter `metadata`
  - removed the optional property `items/metadata` from the response with the `200` status
  - added the new optional `query` request parameter `tags`
  - added the optional property `items/tags` to the response with the `200` status
- **2026-03-07** `48572ed07140` — 2 info
  - added the new optional `query` request parameter `metadata`
  - added the optional property `items/metadata` to the response with the `200` status
- **2026-01-27** `fbe706932aed` — 1 info
  - added the optional property `items/builder_instance_id` to the response with the `200` status
- **2026-01-09** `cadf3c04bd1b` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kernel/apis/hypeman-api/changes/builds/get.md)

---

[API](https://skmtc.dev/kernel/apis/hypeman-api.md) · [All operations](https://skmtc.dev/kernel/apis/hypeman-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kernel/hypeman-api/revisions/b4642bb950dc/schema)