> ## 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.

# List Builds

> Every build uploaded to a project with its pipeline phase, and for builds still in flight, their place in the region's queue.

Return every build on a project, newest first, with where each one is in the pipeline. Builds that are still being processed also carry their queue position and a verdict, so a CI job can poll this one endpoint after [Upload File](/resources/api-reference/upload-file-api) instead of guessing.

<Info>
  Scope: `read`. A build is called a *file* in the API because that is what the pipeline receives: a `.zip`. `uploadId` from Upload File, `fileId` here and `buildId` on the control endpoints are the same value.
</Info>

## Prerequisites

| Requirement         | Where to get it                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Project ID          | [Finding your IDs](/resources/api-reference/finding-your-user-and-project-ids) or [List Projects](/resources/api-reference/list-projects) |
| API key with `read` | [API authentication](/resources/api-reference/api-authentication)                                                                         |

## Path parameters

<ParamField path="projectId" type="string" required>
  The project whose builds to list. Must belong to the key's account.
</ParamField>

## Headers

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

## Response

<ResponseField name="projectId" type="string">
  The project id.
</ResponseField>

<ResponseField name="region" type="string">
  The project's region: `US-East-1`, `Europe`, `Asia Pacific` or `Australia`. Builds are distributed to this region's streaming servers.
</ResponseField>

<ResponseField name="autoRelease" type="boolean">
  When `false`, processed builds stop at `Ready` until you set one active.
</ResponseField>

<ResponseField name="liveBuildId" type="string | null">
  The build currently served to viewers, or `null` if none is approved.
</ResponseField>

<ResponseField name="total" type="number">
  Number of builds on the project.
</ResponseField>

<ResponseField name="files" type="array">
  One entry per build, newest first.

  <Expandable title="Build fields">
    <ResponseField name="id" type="string">
      The build id. Use it for [Build Status](/resources/api-reference/build-status) and [Set Active Build](/resources/api-reference/set-active-build).
    </ResponseField>

    <ResponseField name="status" type="string">
      Raw pipeline status: `pending`, `Downloading Files`, `Extracting & Scanning`, `Saving to Repository`, `Ready`, `Distribute`, `Distributing to Servers`, `Approved`, `Download Failed`, `Reject`.
    </ResponseField>

    <ResponseField name="phase" type="string">
      The status as a stable word: `waiting`, `downloading`, `scanning`, `saving`, `ready`, `queued`, `distributing`, `live`, `failed`, `rejected`.
    </ResponseField>

    <ResponseField name="uploadedAt" type="string | null">
      ISO 8601 upload time.
    </ResponseField>

    <ResponseField name="statusUpdatedAt" type="string | null">
      ISO 8601 time the status last changed. `null` on builds uploaded before this field existed.
    </ResponseField>

    <ResponseField name="note" type="string | null">
      The pipeline's or an operator's reason when a build failed or was rejected.
    </ResponseField>

    <ResponseField name="unrealVersion" type="string | null">
      Engine version detected in the build.
    </ResponseField>

    <ResponseField name="psVersion" type="number | null">
      Pixel Streaming plugin generation detected: `1` or `2`.
    </ResponseField>

    <ResponseField name="queue" type="object | null">
      Present only while the build is in flight: `inQueue`, `position`, `ahead` (builds ahead of it in the region), `processingNow`.
    </ResponseField>

    <ResponseField name="state" type="string">
      Present only while in flight. The verdict from [Build Status](/resources/api-reference/build-status): `queued`, `processing`, `stalled`, `no_builder_online`, `ready_for_activation`.
    </ResponseField>

    <ResponseField name="verdict" type="string">
      Present only while in flight. One sentence explaining `state`.
    </ResponseField>

    <ResponseField name="likelyStuck" type="boolean">
      Present only while in flight. `true` when the wait is not a normal queue wait.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="queue" type="object | null">
  Present when any build is in flight: `region`, `totalInQueue` (all entries in the region's queue, including other customers', counted only), and `builders` (`total`, `online`, `busy`, `idle`, `lastReportAt`).
</ResponseField>

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

  ```javascript Node.js theme={"dark"}
  const res = await fetch(
    'https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/files',
    { headers: { 'x-api-key': process.env.STREAMPIXEL_API_KEY } }
  );
  const { files, liveBuildId } = await res.json();
  const inFlight = files.filter((f) => f.state);
  ```

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

  r = requests.get(
      "https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/files",
      headers={"x-api-key": os.environ["STREAMPIXEL_API_KEY"]},
  )
  data = r.json()
  in_flight = [f for f in data["files"] if "state" in f]
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {
    "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
    "region": "Europe",
    "autoRelease": true,
    "liveBuildId": "665a2b3c4d5e6f7a8b9c0e1f",
    "total": 2,
    "files": [
      {
        "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,
        "queue": { "inQueue": true, "position": 2, "ahead": 1, "processingNow": false },
        "state": "queued",
        "verdict": "Genuinely queued: 1 build ahead of it in this region, the oldest queued 14 min ago, and the build machine is busy on one of them. It is processed in order.",
        "likelyStuck": false
      },
      {
        "id": "665a2b3c4d5e6f7a8b9c0e1f",
        "status": "Approved",
        "phase": "live",
        "uploadedAt": "2026-09-20T15:02:11.000Z",
        "statusUpdatedAt": "2026-09-20T15:41:03.000Z",
        "note": null,
        "unrealVersion": "5.4",
        "psVersion": 2,
        "appPath": "665a2b3c4d5e6f7a8b9c0e1f",
        "lastRetryError": null,
        "lastRetryAt": null
      }
    ],
    "queue": {
      "region": "Europe",
      "totalInQueue": 2,
      "builders": { "total": 1, "online": 1, "busy": 1, "idle": 0, "lastReportAt": "2026-09-26T09:45:12.000Z", "redisTrouble": false }
    }
  }
  ```
</ResponseExample>

## Errors

| Status | `code`          | Cause                                   |
| ------ | --------------- | --------------------------------------- |
| `403`  | `API_KEY_SCOPE` | The key lacks the `read` scope.         |
| `403`  | —               | The project belongs to another account. |
| `404`  | `NOT_FOUND`     | No project with that id.                |

## Next steps

<CardGroup cols={2}>
  <Card title="Build Status" icon="magnifying-glass" href="/resources/api-reference/build-status">
    One build's queue position and a verdict on whether the wait is genuine.
  </Card>

  <Card title="Set Active Build" icon="star" href="/resources/api-reference/set-active-build">
    Make a processed build the one viewers get.
  </Card>
</CardGroup>