// Deployments

List deployments

Page through the deployments of a workspace, a project or a single release - and poll for what has changed.

GET/api/deployment/list

Description

Returns one page of deployments, most recently changed first.

Scope is required, and it is exactly one of workspaceId, projectId or releaseId. Sending none of them, or more than one, is a 400 - there is no unscoped read of every deployment in the organization. Adding version to a projectId narrows the read to that one release, resolved the same way Get a release resolves it.

Each entry is a summary: what was deployed where, by whom, when it last changed, and its status and error counts. The logs are not here - those are on Get deployment status, one deployment at a time.

One deployment targets exactly one environment. A deploy or promote that named three environments produced three deployments, and all three appear here separately.

A workspace-wide read shows the projects this service account may see and silently leaves the rest out. Asking about a workspace is a fair question even when part of it is none of your business, so widening the scope never turns into a permission error over one project. Naming a project or a release you may not see is a different matter, and is refused.

Parameters

NameInTypeRequiredDescription
workspaceId query string no Every deployment of every project in this workspace that you are allowed to see. Give exactly one of workspaceId, projectId or releaseId.
projectId query string no Every deployment of this project. Give exactly one of the three scope parameters.
releaseId query string no Every deployment of this one release. Give exactly one of the three scope parameters.
version query string no Narrows a projectId read to the release carrying this version. Only valid together with projectId - on its own it is a 400. Matched exactly first, then as a SemVer equivalent, so 6.1 finds 6.1.0.
changedSince query string no ISO 8601 date and time, e.g. 2026-09-02T14:05:00Z. Only deployments that changed strictly after it are returned, and the sort flips to oldest change first. See below.
max query integer no Deployments per page. Defaults to 100 and is clamped to the range 1-500 rather than rejected.
cursor query string no Continuation token from the previous response's nextCursor. Omit it to read the first page. See below.

Polling for what has changed

changedSince is the field to build a reporter on. Only deployments whose changedUtc is strictly after it come back, so the same value never hands you the same row twice.

The sort direction flips with it, deliberately.

  • Without changedSince you are browsing, and the most recent change comes first.
  • With changedSince you are catching up, and the oldest change comes first - so you walk forward through what happened and can stop anywhere with a coherent position behind you.

The loop is: take the highest changedUtc in what you were given, hand it back as the next changedSince, repeat. Use the value from the response rather than your own clock; the timestamps are the server's, and your clock is not.

Ordering is by when a deployment last changed rather than when it was created, because the column a page boundary sits on has to be the column the filter uses. That column is written when the row is created, refreshed while the deployment runs, and updated on every status transition. For rows written before every writer set it, changedUtc falls back to the creation date, so a deployment always has a place in the timeline.

Keep changedSince on every request of the same walk. Dropping it midway flips the direction, and the cursor you are holding is then read the other way round.

Paging

Paging is by cursor, exactly as on List releases. Read the first page without cursor, hand each response's nextCursor back as the next cursor, and keep going until it comes back null.

A short page is not the last page - only a null cursor is. The token is opaque, and one that does not decode is refused with 400 rather than quietly restarting you at page one.

Field casing

This endpoint answers in lower camel case - deploymentId, errorCount - as every listing in this reference does. Get deployment status is the exception: its status object and log entries are Pascal case (Status, ErrorCount). The two shapes describe the same deployment and cannot share a parser.

Status values

status is one of Queued, Validating, AwaitingSlot, Running, Completed, Failed or Cancelled.

Completed, Failed and Cancelled are terminal - a deployment in one of them will not change again. The other four are transient, and a deployment can move between AwaitingSlot and Validating more than once before it runs.

Completed means the engine reached the end of the step list, not that the deployed work was healthy. That is the separate question errorCount answers, and Get deployment status covers both in full.

Response

FieldTypeDescription
workspaceId string Echoed back when you asked by workspace, otherwise null.
projectId string Echoed back when you asked by project, otherwise null.
releaseId string The release you asked by - or, for a projectId and version read, the release that version resolved to. null otherwise. That makes this the cheapest way to turn a version into a release id.
deployments object[] One page of deployments. Empty array when nothing matches - including when a workspace holds no project you may see, which is not an error.
deployments[].deploymentId string Pass it to Get deployment status or Cancel a deployment.
deployments[].status string (enum) Queued, Validating, AwaitingSlot, Running, Completed, Failed or Cancelled. See below.
deployments[].projectId string The project the deployed release belongs to.
deployments[].projectName string That project's name as it reads now.
deployments[].releaseId string The release that was deployed. Read it with Get a release.
deployments[].releaseVersion string That release's version.
deployments[].environmentId string The one environment this deployment targeted.
deployments[].environmentName string That environment's name, or null when it no longer resolves.
deployments[].createdUtc string When the deployment was created, ISO 8601 with offset.
deployments[].deploymentDateUtc string When it is due to run. The same as createdUtc for an immediate deploy, later for one scheduled with deploymentDateUnixMillis.
deployments[].completeUtc string When it finished, or null while it has not.
deployments[].changedUtc string When it last changed - created, started, retried, finished or cancelled. This is the field the list is ordered and filtered by, and the one to feed back as changedSince.
deployments[].errorCount integer Error-level log entries recorded so far. It only grows, and it counts log lines rather than failed steps. A Completed deployment can still have a non-zero count.
deployments[].warningCount integer The same count for warning-level entries.
deployments[].automated boolean true when a lifecycle started this deployment on its own, rather than a person or a pipeline asking for it.
deployments[].createdBy object Who started it: userId, name, email. null for an automated deployment, or when the creator no longer resolves.
nextCursor string Pass back as cursor to read the next page. null means this page was the last one.

Errors

StatusMeaning
400 None of workspaceId, projectId and releaseId was given, or more than one was - the response reads give exactly one of workspaceId, projectId or releaseId.
400 version was sent without projectId - the response reads version only applies together with projectId.
400 changedSince is not an ISO 8601 date and time. The message names the format it wanted, e.g. 2026-09-02T14:05:00Z.
400 cursor is not a token this endpoint issued - the response reads invalid cursor.
400 Invalid workspaceId, projectId or releaseId, or no release with that version exists for the project. A resource in another organization is reported the same way as one that does not exist.
401 Missing or invalid Basic auth credentials, or the service account lacks permission to view deployments of the project or release you named. A workspace read never fails this way - projects you cannot see are left out of the page instead.