---
title: "Get build status"
method: GET
path: "/v1/builds/{id}"
tags: ["builds"]
---

# Get build status

`GET /v1/builds/{id}`

Returns the current state of a build. While the build is in
progress, `status` is `pending` or `running` and `progress`
contains a human-readable string describing the current phase
(e.g. `Pulling image`, `Building (3 steps)`, `Settling VM`).

On success, `status` is `completed` and `snapshotId` references a
`ready` snapshot — fetch it via `GET /v1/snapshots/{id}`.
On failure, `status` is `failed` and `error` carries the worker's
diagnostic.

## Response `200`

Build status

- BuildResponse — Build state snapshot. Returned by `POST /v1/builds` (initial `pending` state) and `GET /v1/builds/{id}` (current state on each poll).
  - `id` string, required — Build ID (UUID). Use this to poll status.
  - `name` string
  - `status` string, required — Current state. Known values: `pending` (accepted, not yet started), `running` (worker is executing), `completed` (snapshot is ready), `failed` (build did not produce a snapshot). Additional values may be introduced in future server versions; clients should treat unknown values as "in progress" rather than as hard errors.
  - `snapshotId` string — Set when `status` is `completed`. Fetch the corresponding Snapshot record via `GET /v1/snapshots/{id}`.
  - `imageRef` string, required
  - `progress` string — Human-readable phase string while the build runs (e.g. `creating build VM`, `buildah pull`, `buildah bud`, `applying image`, `settling VM`, `creating snapshot`). Not present after a terminal status.
  - `error` string — Set when `status` is `failed`. Diagnostic from the worker (truncated to ~4 KiB).
  - `createdAt` string, date-time, required

## Other responses

- `401` — Missing or invalid credentials
- `404` — Resource not found
- `500` — Internal server error

## Changes

- **2026-05-09** `480d9714a7a5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/fastvm-org/apis/fastvm-api/changes/v1/builds/:id/get.md)

---

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