> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Build Status

> Where one build is in the regional pipeline: its queue position, whether a build machine is on it, and a verdict on whether the wait is genuine or the build is stuck.

Answer the question "my build has been distributing for an hour, is that normal?". The endpoint reads the region's build queue and the build machines' heartbeats and returns one `state`, a plain-language `verdict` and an `action`.

<Info>
  Scope: `read`. Other customers' builds share the regional queue; they are **counted** in `ahead` and `totalInQueue` but never identified.
</Info>

## How a build moves

```text theme={"dark"}
pending → Downloading Files → Extracting & Scanning → Saving to Repository
        → Ready (auto-release off)  or  Distribute → Distributing to Servers → Approved
        ↘ Download Failed / Reject
```

Each region has one build queue, processed in order by that region's build machine. A build waits its turn, is downloaded, scanned and saved, and once set active is copied to every streaming server in the region. `Approved` means it is on every server and serving sessions.

## States

| `state`                | Meaning                                                                                                        | `likelyStuck`  |
| ---------------------- | -------------------------------------------------------------------------------------------------------------- | -------------- |
| `queued`               | In the region's queue with builds ahead of it and a build machine online. A genuine wait.                      | `false`        |
| `processing`           | A build machine has taken it, or it is first in line and the machine is busy.                                  | `false`        |
| `ready_for_activation` | Processed; auto-release is off, so it waits for [Set Active Build](/resources/api-reference/set-active-build). | `false`        |
| `stalled`              | First in line but not picked up, or the status says in-flight while the queue no longer holds it.              | usually `true` |
| `no_builder_online`    | No build machine in the region has reported for over three minutes. Nothing moves until it is back.            | `true`         |
| `live`                 | Approved and serving.                                                                                          | `false`        |
| `failed`               | Download failed; see `build.note`.                                                                             | `false`        |
| `rejected`             | Rejected by the pipeline or an operator; see `build.note`.                                                     | `false`        |

## Path parameters

<ParamField path="projectId" type="string" required>
  The project the build belongs to.
</ParamField>

<ParamField path="buildId" type="string" required>
  The build id (`uploadId` from Upload File, `id` from [List Builds](/resources/api-reference/list-builds)).
</ParamField>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your Streampixel API key.
</ParamField>

## Response

<ResponseField name="state" type="string">
  One of the states above.
</ResponseField>

<ResponseField name="likelyStuck" type="boolean">
  `true` when the wait is not a normal queue wait and something should be done.
</ResponseField>

<ResponseField name="verdict" type="string">
  One or two sentences explaining `state`, written for the project owner.
</ResponseField>

<ResponseField name="action" type="string | null">
  What to do, or `null` when nothing is needed.
</ResponseField>

<ResponseField name="status" type="string">
  Raw pipeline status of the build.
</ResponseField>

<ResponseField name="phase" type="string">
  The status as a stable word (see [List Builds](/resources/api-reference/list-builds)).
</ResponseField>

<ResponseField name="meaning" type="string">
  What the current status means.
</ResponseField>

<ResponseField name="inStateSince" type="string | null">
  ISO 8601 time the status last changed.
</ResponseField>

<ResponseField name="minutesInState" type="number | null">
  Minutes since then.
</ResponseField>

<ResponseField name="isLive" type="boolean">
  Whether this build is the one currently served.
</ResponseField>

<ResponseField name="build" type="object">
  The build entry, as in [List Builds](/resources/api-reference/list-builds).
</ResponseField>

<ResponseField name="queue" type="object">
  <Expandable title="Queue fields">
    <ResponseField name="inQueue" type="boolean">Whether the build's entry is still in the region's queue.</ResponseField>
    <ResponseField name="position" type="number | null">1-based position; `1` is being processed or next.</ResponseField>
    <ResponseField name="ahead" type="number | null">Entries ahead of it, any customer's.</ResponseField>
    <ResponseField name="processingNow" type="boolean">A build machine has taken this entry.</ResponseField>
    <ResponseField name="queuedAt" type="string | null">When this entry was queued.</ResponseField>
    <ResponseField name="oldestAheadQueuedAt" type="string | null">When the oldest entry ahead was queued: how long the queue has been backed up.</ResponseField>
    <ResponseField name="totalInQueue" type="number">All entries in the region's queue.</ResponseField>
    <ResponseField name="entryType" type="string | null">`Download File` or `Distribute File`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="builders" type="object">
  The region's build machines from their heartbeats: `total`, `online` (reported within three minutes), `busy`, `idle`, `lastReportAt`, `redisTrouble`.
</ResponseField>

<ResponseField name="checkedAt" type="string">
  When this answer was computed.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/files/66a0b1c2d3e4f5a6b7c8d9e0/status \
    -H "x-api-key: $STREAMPIXEL_API_KEY"
  ```

  ```javascript Node.js theme={"dark"}
  // Poll until the build is live or something needs attention.
  const url = `https://platform.streampixel.io/api/v1/projects/${projectId}/files/${buildId}/status`;
  for (;;) {
    const s = await (await fetch(url, { headers: { 'x-api-key': process.env.STREAMPIXEL_API_KEY } })).json();
    console.log(s.state, '-', s.verdict);
    if (s.state === 'live') break;
    if (s.likelyStuck || ['failed', 'rejected'].includes(s.state)) throw new Error(`${s.state}: ${s.action ?? s.build.note}`);
    await new Promise((r) => setTimeout(r, 30_000));
  }
  ```

  ```python Python theme={"dark"}
  import os, time, requests

  url = f"https://platform.streampixel.io/api/v1/projects/{project_id}/files/{build_id}/status"
  while True:
      s = requests.get(url, headers={"x-api-key": os.environ["STREAMPIXEL_API_KEY"]}).json()
      print(s["state"], "-", s["verdict"])
      if s["state"] == "live":
          break
      if s["likelyStuck"] or s["state"] in ("failed", "rejected"):
          raise SystemExit(f'{s["state"]}: {s.get("action") or s["build"]["note"]}')
      time.sleep(30)
  ```
</RequestExample>

<ResponseExample>
  ```json queued theme={"dark"}
  {
    "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
    "region": "Europe",
    "autoRelease": true,
    "build": { "id": "66a0b1c2d3e4f5a6b7c8d9e0", "status": "Distributing to Servers", "phase": "distributing", "uploadedAt": "2026-09-26T09:12:04.000Z", "statusUpdatedAt": "2026-09-26T09:31:40.000Z", "note": null, "unrealVersion": "5.4", "psVersion": 2, "appPath": null, "lastRetryError": null, "lastRetryAt": null },
    "isLive": false,
    "status": "Distributing to Servers",
    "phase": "distributing",
    "meaning": "Being copied to every streaming server in the region. Sessions can start once it is Approved.",
    "inStateSince": "2026-09-26T09:31:40.000Z",
    "minutesInState": 14,
    "state": "queued",
    "likelyStuck": false,
    "verdict": "Genuinely queued: 1 build ahead of it in this region, the oldest queued 22 min ago, and the build machine is busy on one of them. It is processed in order.",
    "action": "Wait; nothing to do. If the queue has not moved in an hour, contact support.",
    "queue": { "inQueue": true, "position": 2, "ahead": 1, "processingNow": false, "queuedAt": "2026-09-26T09:31:40.000Z", "oldestAheadQueuedAt": "2026-09-26T09:23:10.000Z", "totalInQueue": 2, "entryType": "Distribute File" },
    "builders": { "total": 1, "online": 1, "busy": 1, "idle": 0, "lastReportAt": "2026-09-26T09:45:12.000Z", "redisTrouble": false },
    "checkedAt": "2026-09-26T09:45:40.000Z"
  }
  ```

  ```json stalled theme={"dark"}
  {
    "state": "stalled",
    "likelyStuck": true,
    "status": "Distributing to Servers",
    "minutesInState": 47,
    "verdict": "Status has said \"Distributing to Servers\" for 47 minutes and the build is not in the region's queue any more. The pipeline lost track of it (a build machine restart mid-build is the usual cause).",
    "action": "Retry the build from the dashboard (re-queues the download); if it stalls again, contact support with the build id.",
    "queue": { "inQueue": false, "position": null, "ahead": null, "processingNow": false, "queuedAt": null, "oldestAheadQueuedAt": null, "totalInQueue": 0, "entryType": null },
    "builders": { "total": 1, "online": 1, "busy": 0, "idle": 1, "lastReportAt": "2026-09-26T10:18:02.000Z", "redisTrouble": false }
  }
  ```
</ResponseExample>

## Errors

| Status | `code`          | Cause                                    |
| ------ | --------------- | ---------------------------------------- |
| `403`  | `API_KEY_SCOPE` | The key lacks the `read` scope.          |
| `404`  | `NOT_FOUND`     | No such project, or no such build on it. |

<Tip>
  Poll every 30 to 60 seconds. Distribution of a multi-gigabyte build to a region takes tens of minutes; the verdict tells you when polling is pointless.
</Tip>