Skip to main content

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.

Every build you submit moves through a fixed pipeline. Each state transition fires a webhook, so you can track progress from your own systems instead of polling the dashboard. This page is the reference for what each state means, how long it usually takes, and what can fail along the way.

​
State diagram

The happy path is pending → Downloading Files → Extracting & Scanning → Saving to Repository → Distribute → Approved. A build can exit early to Reject from the Distribute step if validation fails.

​
State reference

Each state corresponds to a webhook event. The event fires when the build enters the state.
StateWebhook eventDescriptionTypical durationPossible failures
pendingbuild.uploadedUpload request accepted; build queued for processing.< 5 secRate limit (1 req per 2 min per user).
Downloading Filesbuild.downloadingStreampixel pulls your .zip from fileUrl.1–10 min depending on size and your hostingURL not publicly accessible, redirects to a login page, transfer aborted.
Extracting & Scanningbuild.extractingArchive is unpacked and scanned for required UE files.1–5 minCorrupt archive, missing executable, malformed package.
Saving to Repositorybuild.savingFiles are stored in Streampixel’s regional build repository.30 sec – 3 minStorage error (rare).
Distributebuild.distributingBuild is being released to GPU workers in the project’s region.1–5 minWorker pool unreachable, build fails sanity check on workers.
Approvedbuild.approvedBuild is live on the fleet and ready to stream.terminal state—
Rejectbuild.rejectedBuild failed at some pipeline stage; reason in objection.terminal state—
Durations are typical, not guaranteed. Large builds (closer to the 30 GB cap), slow source hosts, and busy regions all extend the pipeline.

​
Auto-release vs manual release

The autoRelease flag on the Upload File API controls what happens after Saving to Repository.
The build automatically transitions through Distribute and into Approved. No further action needed — the build goes live as soon as it’s validated.Use this when you want every successful upload to ship.
curl -X POST https://api.streampixel.io/pixelStripeApi/projects/upload-file \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "[YOUR_API_KEY]",
    "userId": "[YOUR_USER_ID]",
    "projectId": "[YOUR_PROJECT_ID]",
    "fileUrl": "https://your-bucket.s3.amazonaws.com/MyBuild.zip",
    "autoRelease": false
  }'
autoRelease only affects the Distribute step. The earlier stages (Downloading, Extracting, Saving) always run automatically.

​
Rejection reasons

When a build ends in Reject, the build.rejected webhook payload includes an objection field describing why. Common causes:
Symptom in objectionRoot cause
”Failed to download file”fileUrl is private, returns HTML, or times out. Use a direct-download S3/GCS link.
”Build contains unsupported file formats”Archive contains files outside the expected UE package layout.
”Missing executable”Packaged folder doesn’t contain the expected .exe. Re-package from the Unreal Editor.
”Archive could not be extracted”Corrupt .zip, encrypted archive, or non-zip format renamed to .zip.
”Validation failed on worker”Build does not launch headlessly on the GPU workers. Check Pixel Streaming plugin and command-line args.
The full objection string is whatever the pipeline produced — surface it directly to your team or CI logs.

​
Watching the pipeline

Two ways to track a build’s progress:

Dashboard

The project’s Builds tab shows the current state of every upload, with timestamps and the objection text on rejection.

Webhooks

HTTP POSTs to your endpoint at every state transition. The recommended path for CI/CD.
Webhook deliveries are not retried. If your endpoint is down when an event fires, you’ll miss it. Listen for build.approved from the dashboard or poll the project state as a fallback.

​
Next steps

Webhooks

Wire up the events that fire at each state transition.

Upload File API

The endpoint that kicks off the lifecycle.

Distribute File API

Used when autoRelease: false.

Uploading your build

The dashboard path for non-automated workflows.