Docs

Get a deployment by id

GET
/deployments/{deployment_id}

Reads one deployment record.

The lookup is scoped to the project in project_id: a deployment id belonging to another project answers not found exactly as an unknown id does, so the endpoint cannot be used to probe for deployments in projects the caller cannot read.

Authorization

headerAuthorizationBearer <token>

Scope: deployment.read

Path Parameters

deployment_id*string

The unique identifier of the deployment.

Match^dep_[a-zA-Z0-9_-]+$

Query Parameters

project_id*string

The unique identifier of the project

Match^[a-zA-Z0-9_-]+$

Response Body

The deployment was retrieved successfully.

application/json
  1. response

An immutable record of a release made live on a set of targets. Deploying and rolling back each append one, so the history is the audit trail.

All primary origins serve the project's newest primary deployment; one added after it serves nothing until the next deployment to primary. A preview URL serves the newest deployment to it while its preview is live.

Every field is fixed at creation except status, which is read as of now.

id*deployment-id

The opaque, immutable resource id, assigned at creation.

Match^dep_[a-zA-Z0-9_-]+$
project_id*project-id

The project this deployment belongs to.

Match^[a-zA-Z0-9_-]+$
release_id*release-id

The release this deployment made live. Always the release id, also when the request named the release by content_hash.

Match^rel_[a-zA-Z0-9_-]+$
kind*DeploymentKind

primary for the project's primary origins, preview for preview URLs.

Value in"primary""preview"
targets*array<>

The resolved origins, sorted. For primary, the project's primary origins at creation. The live view lists only the targets still served.

Items1 <= items
status*DeploymentStatus

Whether the deployment serves its release now.

  • live — at least one of its targets serves it now.
  • inactive — none does: a later deployment replaced it, or its previews expired or were removed.
Value in"live""inactive"
deployed_at*string

When the deployment was created.

Formatdate-time
metadata*

Why the release went live and who made it happen.

release?

The release named by release_id, present only when the request asked for it with expand: ["release"] — the same representation GET /releases/{release_id} serves. Absent means it was not requested.

Example Request
import { configureZitadel, getApi } from "@zitadel/api/config";// In the browser, through the SDK proxy: the session cookie authenticates the call.const client = getApi(configureZitadel({ projectId: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" }));const deployment = await client.getDeploymentById(  "dep_01KX4SB9C8E1F0N9WD3P2E4YM5",  { project_id: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" },);
Example Response

Every primary origin the deployment made the release live on, also after a later primary deployment replaced it, as status: inactive says.

{  "id": "dep_01KX5N7C9D2E7F0N9WD3P2E4YM6",  "project_id": "proj_01KWH1P4MYS7F0N9WD3P2E4YM5",  "release_id": "rel_01KX3RG8A7F0N9WD3P2E4YM5C1",  "kind": "primary",  "targets": [    {      "origin": "https://app.acme.com"    },    {      "origin": "https://www.acme.com"    }  ],  "status": "inactive",  "deployed_at": "2026-10-02T14:52:00Z",  "metadata": {    "reason": "deploy",    "message": "add phone_number to human-user",    "rollback_to": null,    "deployed_by": "user_01KWH3B72K7M7F0N9WD3P2E4YM",    "deployed_by_type": "human"  }}

Was this helpful?