Docs

List deployments

GET
/deployments

Lists what ran where, and when.

By default the list is the history, newest first: every deployment of the project with every target it made the release live on. With origin, the history of that origin alone.

With live=true, the list is what is served now, newest first: the project's newest primary deployment, narrowed to origins that are still primary, and the newest deployment to each live preview URL, narrowed to the URLs it still serves. Combined with origin, it is the one deployment that origin serves, or empty.

expand: ["release"] embeds the release each deployment made live; it requires release.read and does not change the ordering or the page tokens.

Authorization

headerAuthorizationBearer <token>

Scope: deployment.read

Query Parameters

project_id*string

The unique identifier of the project

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

Narrows the list to the deployments that targeted this origin, given exactly as the deployment records it. An origin no deployment targeted answers an empty list, not an error.

Match^https?://(\[[0-9a-f:.]+\]|[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*)(:(6553[0-5]|655[0-2][0-9]|65[0-4][0-9]{2}|6[0-4][0-9]{3}|[1-5][0-9]{4}|[1-9][0-9]{0,3}))?$
Lengthlength <= 2048
live?boolean

Lists what each target serves now instead of the history. Defaults to false.

Defaultfalse
expand?array<>

Related objects to embed on each returned deployment.

limit?integer

Maximum number of items to return.

Range1 <= value <= 100
Default20
page_token?string

Token for fetching the next page of results. Obtain this value from next_page_token in the previous response. Omit to start from the beginning. Its format is opaque and may change between releases.

Response Body

The deployments were listed successfully.

application/json
  1. response

One page of deployments, ordered as the operation describes.

deployments*array<>
next_page_token?|

Token to pass as page_token in the next request to fetch the following page. Absent when there are no more results.

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 deployments = await client.listDeployments({ project_id: "proj_01KWH1P4MYS7F0N9WD3P2E4YM5" });
Example Response

A later deployment to primary replaced the earlier one on every primary origin, so the earlier one is inactive. The preview deployment still serves its URL.

{  "deployments": [    {      "id": "dep_01KX6P8D0E3F7F0N9WD3P2E4YM7",      "project_id": "proj_01KWH1P4MYS7F0N9WD3P2E4YM5",      "release_id": "rel_01KX2QF7Z6D0F0N9WD3P2E4YM40",      "kind": "primary",      "targets": [        {          "origin": "https://app.acme.com"        },        {          "origin": "https://www.acme.com"        }      ],      "status": "live",      "deployed_at": "2026-10-02T15:03:00Z",      "metadata": {        "reason": "rollback",        "message": "phone_number broke sign-up",        "rollback_to": "dep_01KX4SB9C8E1F0N9WD3P2E4YM5",        "deployed_by": "user_01KWH3B72K7M7F0N9WD3P2E4YM",        "deployed_by_type": "human"      }    },    {      "id": "dep_01KX5Q2R8D2E7F0N9WD3P2E4YM8",      "project_id": "proj_01KWH1P4MYS7F0N9WD3P2E4YM5",      "release_id": "rel_01KX3RG8A7F0N9WD3P2E4YM5C1",      "kind": "preview",      "targets": [        {          "origin": "https://acme-git-sso-acmeinc.vercel.app",          "expires_at": "2026-10-09T14:58:00Z"        }      ],      "status": "live",      "deployed_at": "2026-10-02T14:58:00Z",      "metadata": {        "reason": "deploy",        "message": null,        "rollback_to": null,        "deployed_by": null,        "deployed_by_type": null      }    },    {      "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": null,        "deployed_by_type": null      }    },    {      "id": "dep_01KX4SB9C8E1F0N9WD3P2E4YM5",      "project_id": "proj_01KWH1P4MYS7F0N9WD3P2E4YM5",      "release_id": "rel_01KX2QF7Z6D0F0N9WD3P2E4YM40",      "kind": "primary",      "targets": [        {          "origin": "https://app.acme.com"        },        {          "origin": "https://www.acme.com"        }      ],      "status": "inactive",      "deployed_at": "2026-10-01T09:30:00Z",      "metadata": {        "reason": "deploy",        "message": "initial import",        "rollback_to": null,        "deployed_by": null,        "deployed_by_type": null      }    }  ],  "next_page_token": null}

Was this helpful?