---
title: "List deployments"
method: POST
path: "/v2/deployments.listDeployments"
tags: ["deployments"]
---

# List deployments

`POST /v2/deployments.listDeployments`

Retrieve a paginated list of deployments within a workspace, newest first.

Filter by project, app, environment, and lifecycle status. All filters are
optional; with none set, every deployment in the workspace is returned.
Filters nest: `app` requires `project`, and `environment` requires both
`project` and `app`. Results are paginated; when `hasMore` is true, pass the
returned `cursor` to fetch the next page.

**Required Permissions**

Your root key must have the `environment.*.read_deployment` permission.
Listing spans environments, so a grant on a single environment is not
sufficient.

## Request body

- V2DeploymentsListDeploymentsRequestBody — Filter deployments within a workspace. All filters are optional; with none set, every deployment in the workspace is returned, newest first.
  - `project` string — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `app` string — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `environment` string — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `status` DeploymentStatus[] — Restrict results to deployments in any of the given lifecycle statuses. Omit to return deployments in every status.
  - `limit` integer — Maximum number of deployments to return per request. Balance between response size and number of pagination calls needed.
  - `cursor` string — Pagination cursor from a previous response to fetch the next page. Use when `hasMore: true` in the previous response.

## Response `200`

Successfully retrieved a paginated list of deployments. Use the pagination cursor for additional results when `hasMore: true`.

- V2DeploymentsListDeploymentsResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` Deployment[], required — Array of deployments, ordered newest first.
    - `id` string, required — The unique identifier of the deployment, generated by Unkey.
    - `status` 'pending' | 'starting' | 'building' | 'deploying' | 'network' | 'finalizing' | 'ready' | 'failed' | 'skipped' | 'awaiting_approval' | 'stopped' | 'superseded' | 'cancelled', required — Current lifecycle status of the deployment. Poll until it reaches a terminal state: ready (serving), failed, skipped, superseded, stopped, or cancelled.
    - `isCurrent` boolean, required — True when this is the production deployment currently serving traffic, i.e. on api.acme.com. Only production deployments can be current, and at most one deployment is current. Rollbacks and promotions change which deployment is current and serves requests to api.acme.com.
    - `environment` string, required — Slug of the environment this deployment belongs to.
    - `app` string, required — Slug of the app this deployment belongs to.
    - `project` string, required — Slug of the project this deployment belongs to.
    - `git` DeploymentGit
      - `commitSha` string, required — The git commit SHA this deployment was built from.
      - `branch` string — The git branch this deployment was built from. Omitted when unknown.
    - `docker` DeploymentDocker
      - `image` string, required — The Docker image this deployment runs.
    - `availableActions` DeploymentAction[], required — Lifecycle operations you are allowed to call on this deployment right now. Empty when none apply (e.g. while building or in a terminal state).
    - `regions` string[], required — Regions this deployment is configured to run in. Empty while the deployment has no scheduled regions yet.
    - `error` DeploymentError
      - `code` 'no_schedulable_regions' | 'invalid_runtime_settings' | 'cpu_quota_exceeded' | 'memory_quota_exceeded' | 'storage_quota_exceeded' | 'build_failed' | 'unknown', required — The reason a deployment failed. `unknown` means Unkey could not classify the failure; see `message` for details.
      - `step` string, required — The pipeline step that failed (e.g. `building`, `deploying`, `starting`).
      - `message` string, required — Human-readable description of why the deployment failed. For programmatic handling, use `code`.
    - `domains` string[] — Public hostnames this deployment is reachable at.
    - `runtime` DeploymentRuntime, required
      - `vCpus` number, double, required — CPU allocation in vCPUs (1 = one vCPU, 0.5 = half a vCPU).
      - `memoryMib` integer, required — Memory allocation in mebibytes.
      - `storageMib` integer, required — Ephemeral storage allocation in mebibytes.
      - `port` integer, required — Port the container listens on.
      - `command` string[], required — Container entrypoint command override. Empty when none is set.
      - `shutdownSignal` 'SIGTERM' | 'SIGINT' | 'SIGQUIT' | 'SIGKILL', required — Signal sent to the container on shutdown.
      - `upstreamProtocol` 'http1' | 'h2c', required — Protocol used to reach the container.
      - `healthcheck` EnvironmentHealthcheck
        - `method` 'GET' | 'POST', required — HTTP method used to probe the container.
        - `path` string, required — HTTP path probed on the container. Must start with a slash.
        - `intervalSeconds` integer — How often the probe runs, in seconds. Defaults to 10 when omitted.
        - `timeoutSeconds` integer — Per-probe timeout, in seconds. Defaults to 5 when omitted.
        - `failureThreshold` integer — Consecutive failures before the container is restarted. Defaults to 3 when omitted.
        - `initialDelaySeconds` integer — Delay before the first probe runs, in seconds. Defaults to 0 when omitted.
    - `createdAt` integer, required — Unix timestamp in milliseconds when the deployment was created.
    - `updatedAt` integer — Unix timestamp in milliseconds when the deployment was last updated. Omitted if the deployment has never been updated.
  - `pagination` Pagination, required — Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
    - `cursor` string — Opaque pagination token for retrieving the next page of results. Include this exact value in the cursor field of subsequent requests. Cursors are temporary and may expire after extended periods.
    - `hasMore` boolean, required — Indicates whether additional results exist beyond this page. When true, use the cursor to fetch the next page. When false, you have reached the end of the result set.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Insufficient permissions (requires `environment.*.read_deployment`)
- `404` — Not Found - A referenced project, app, or environment does not exist in your workspace
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/versions/fa78aafac89c/schema)