Skip to navigation
RESTAdminManagementInfrastructure HostingDeployments

Get Deployment Event Stream

Beta

Opens a server-sent events (SSE) stream that delivers real-time deployment progress updates. The stream remains open until the deployment completes, fails, or the connection times out (30 seconds).

Each event is a JSON object delivered as an SSE data field. Parse the data value as JSON before reading the fields below.

Event payload

FieldTypeDescription
deployment_uuidstringThe UUID of the deployment the event belongs to.
deployment_statusstringOne of queued, in_progress, failed, or completed.
eventobjectThe current step and progress. Omitted when no step information is available yet.
event.stepstringOne of initializing, downloading, unzipping, processing, deploying, finalizing, or complete.
event.progressintegerPercentage complete, from 0 to 100.
errorobjectPresent only when deployment_status is failed. Contains a numeric code.

If the deployment cannot be found after the stream opens, the stream delivers a single event whose data is {"error": "The requested deployment was not found."} and then closes. | deployment_hostnames | array of strings | Hostnames serving the deployment. Always present, but empty ([]) until the deployment reaches finalizing. Prefix the first entry with https:// to build the deployment URL. |

Not every step appears in every deployment, so drive any progress display from the event.step and event.progress values as they arrive rather than expecting a fixed sequence.

Deployment error codes

When deployment_status is failed, error.code identifies the failure reason:

CodeMeaningWhat to do
10An internal error occurred while processing the deployment.Retry the deployment. If it keeps failing, contact support.
20The uploaded bundle could not be retrieved.Usually transient — retry the deployment.
30The bundle could not be extracted.The archive is corrupted, or the build output exceeds the size limits (64 MB compressed, 512 MB uncompressed). Reduce your build size or rebuild and redeploy.
40The build output is invalid.Check that worker.js is 64 MB or smaller, that no individual asset exceeds 25 MB, and that the bundle contains no more than 1,000 files.
50The deployment step failed.Usually transient — retry the deployment. If it persists, contact support.
60The code deployed, but the deployment URL could not be determined.Retry the deployment. If it persists, contact support.

Treat any other code as an unexpected failure: retry the deployment, and contact support if it persists.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI NamePermissionParameter
Infrastructure Deploymentsread-onlystore_infrastructure_deployments_read_only
Infrastructure Deploymentscreate previewstore_infrastructure_deployments_create_preview
Infrastructure Deploymentsmanagestore_infrastructure_deployments_manage
Infrastructure Projectsread-onlystore_infrastructure_projects_read_only
Infrastructure Projectsmanagestore_infrastructure_projects_manage
Infrastructure Logsread-onlystore_infrastructure_logs_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

Path parameters

deployment_uuidstringRequiredformat: "uuid"
The UUID of the deployment to stream events for.
store_hashstringRequired
Permanent ID of the BigCommerce store.

Response

A stream of server-sent events with deployment progress updates. The data attribute is stringified JSON.

deployment_uuidstringformat: "uuid"
The UUID of the deployment.
deployment_statusenum
The current status of the deployment.
Allowed values:
deployment_hostnameslist of strings

The hostnames serving the deployment. Always present, but empty until the deployment reaches finalizing. Prefix the first entry with https:// to build the deployment URL.

eventobjectOptional
Details about the current deployment step and progress. Omitted when no step information is available yet.
errorobjectOptional

Error information if the deployment failed. Present only when deployment_status is failed.

Errors

400
Bad Request Error