curl https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/files/66a0b1c2d3e4f5a6b7c8d9e0/status \
-H "x-api-key: $STREAMPIXEL_API_KEY"
// 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));
}
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)
{
"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"
}
{
"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 }
}
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.
GET
/
api
/
v1
/
projects
/
{projectId}
/
files
/
{buildId}
/
status
curl https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/files/66a0b1c2d3e4f5a6b7c8d9e0/status \
-H "x-api-key: $STREAMPIXEL_API_KEY"
// 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));
}
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)
{
"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"
}
{
"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 }
}
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
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.
state, a plain-language verdict and an action.
Scope:
read. Other customers’ builds share the regional queue; they are counted in ahead and totalInQueue but never identified.How a build moves
pending → Downloading Files → Extracting & Scanning → Saving to Repository
→ Ready (auto-release off) or Distribute → Distributing to Servers → Approved
↘ Download Failed / Reject
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. | 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
string
required
The project the build belongs to.
string
required
The build id (
uploadId from Upload File, id from List Builds).Headers
string
required
Your Streampixel API key.
Response
string
One of the states above.
boolean
true when the wait is not a normal queue wait and something should be done.string
One or two sentences explaining
state, written for the project owner.string | null
What to do, or
null when nothing is needed.string
Raw pipeline status of the build.
string
The status as a stable word (see List Builds).
string
What the current status means.
string | null
ISO 8601 time the status last changed.
number | null
Minutes since then.
boolean
Whether this build is the one currently served.
object
The build entry, as in List Builds.
object
Show Queue fields
Show Queue fields
boolean
Whether the build’s entry is still in the region’s queue.
number | null
1-based position;
1 is being processed or next.number | null
Entries ahead of it, any customer’s.
boolean
A build machine has taken this entry.
string | null
When this entry was queued.
string | null
When the oldest entry ahead was queued: how long the queue has been backed up.
number
All entries in the region’s queue.
string | null
Download File or Distribute File.object
The region’s build machines from their heartbeats:
known, total, online (reported within three minutes), busy, idle, lastReportAt, redisTrouble. When known is false no build machine in the region reports a heartbeat and the verdict rests on the queue alone; no_builder_online is never returned in that case.string
When this answer was computed.
curl https://platform.streampixel.io/api/v1/projects/664f1a2b3c4d5e6f7a8b9c0d/files/66a0b1c2d3e4f5a6b7c8d9e0/status \
-H "x-api-key: $STREAMPIXEL_API_KEY"
// 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));
}
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)
{
"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"
}
{
"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 }
}
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. |
429 | RATE_LIMITED | More than 300 reads in a minute (API-key callers). Retry-After is set. |
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.