Builds

Get build progress

What a build is DOING, as against what became of it. A build is minutes long — most of them spent copying a multi-gigabyte base image and then running your document’s steps — so this says which step of how many is running, and which one failed.

This is the polling half. GET builds/{id}/events is the same thing as an event stream; use that for a terminal and this for anything that reconnects, restarts, or cannot hold a socket open.

It stays readable after the build has finished, so a program that was not attached at the time can still see which step failed.

Needs an account-wide key: one confined to a workspace is a 403.

Requires the viewer role or higher.

get/builds/{id}/progress

Request

  • Base URL: https://app.mandala.computer/api/v1
  • URL: https://app.mandala.computer/api/v1/builds/{id}/progress
  • Auth: HTTP bearer

Path parameters

idstring required

The build id.

Response

Where the build has got to.

idstring

The build this describes.

statusstring

running, succeeded or failed — the job’s own status, restated so one poll answers both questions.

doneboolean

Whether to stop polling. Derived from status and not from phase: a phase is read out of the build’s log, which your own run: steps write into, and only the job decides whether a build worked.

phasestring

Where the build is in itself: planning, staging, copying, building, publishing, and then published, reused or failed. The long ones are copying — the base image is several gigabytes — and building, which is the one with steps in it.

unknown is the one remaining value, and it means the build finished without keeping a step-by-step record — every build from before this endpoint existed is one. It is not reported as published because a build that reused an existing image succeeds too, and that distinction lived in the record that is missing. status is still the answer.

stepinteger

Which step is running, 1-based, or the one that failed. 0 before the build reaches the first.

ofinteger

How many steps there are.

notestring

One line about the phase, or why a failed build failed.

errorstring

Why it failed, when it did. The same value GET builds/{id} gives.

updated_atstring

RFC 3339. When the build last MOVED, and not when this was last read — a build whose steps have stopped advancing is a build whose updated_at stops advancing.

unmatchedboolean

Present and true only when this fleet could not recognise its own build tool’s output, so the per-step position is unavailable. The build itself is unaffected and status is still the answer.

Changes

No recorded changes to this operation across all 1 revision of this API.