---
title: "Get deployment"
method: POST
path: "/v2/deployments.getDeployment"
tags: ["deployments"]
---

# Get deployment

`POST /v2/deployments.getDeployment`

Retrieve a single deployment by its id.

Use this to check a deployment's status after creating it, or to inspect the
runtime configuration of an existing deployment.

**Required Permissions**

Your root key must have one of the following permissions:
- `environment.*.read_deployment` (to read deployments in any environment)
- `environment.<environment_id>.read_deployment` (to read deployments in a specific environment)

## Request body

- V2DeploymentsGetDeploymentRequestBody — Retrieve a single deployment, including its status and runtime configuration.
  - `deploymentId` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

## Response `200`

Successfully retrieved the deployment.

- V2DeploymentsGetDeploymentResponseBody
  - `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
    - `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.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not Found - The requested deployment 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)