---
title: "Get deployment"
method: GET
path: "/api/v1/deployments/{id}"
tags: ["Deployments"]
---

# Get deployment

`GET /api/v1/deployments/{id}`

## Request

- Base URL: `https://previewdrop.dev`
- URL: `https://previewdrop.dev/api/v1/deployments/{id}`
- Auth: HTTP bearer

Returns the current state of a deployment.

**Live status polling**

For deployments with status `queued`, `building`, or `deploying`, the server queries the build worker in real time before responding. This means you always get the freshest status and build log with a single request — no separate logs endpoint needed during the build.

**Expiry**

The build worker marks a deployment `expired` when its TTL elapses and destroys the container. Subsequent polls of this endpoint reflect the `expired` status returned by the worker.

**detected_env_vars**

Once the build completes, `detected_env_vars` is populated with environment variable names that the build process referenced but that were not supplied. This helps diagnose previews that fail silently due to missing config.

**hints** *(failed deployments only)*

When `status` is `failed`, the response includes a top-level `hints` array alongside `deployment`. Each hint has an `id`, `severity` (`error` | `warn` | `tip`), `title`, and `detail`. Use these in CI pipelines to surface actionable guidance without parsing raw log output.

## Path parameters

- `id` string, uuid, required

## Response `200`

OK

- DeploymentWrapper
  - `deployment` Deployment, required: An ephemeral preview deployment.
    - `id` string, uuid, required: Unique deployment identifier.
    - `tenant_id` string, uuid, required: Workspace (tenant) that owns this deployment.
    - `project_id` string, uuid, nullable: ID of the linked project, or `null` for ad-hoc deployments created directly with `repoUrl`.
    - `pd_projects` object, nullable: Nested project record. Only present in **list** responses (`GET /api/v1/deployments`). `null` for ad-hoc deployments with no linked project.
      - `id` string, uuid
      - `name` string
      - `github_repo` string
    - `worker_deploy_id` string, nullable: Internal ID used by the build worker. Use this to correlate with worker logs.
    - `url` string, uri, nullable: Publicly accessible preview URL. Available once status is `ready`. `null` while building.
    - `status` 'queued' | 'building' | 'deploying' | 'ready' | 'failed' | 'expired' | 'stopped', required: Current state of the deployment: - `queued` — accepted, waiting for a build slot - `building` — Docker image is being built - `deploying` — container is starting - `ready` — container is live and reachable via `url` - `failed` — build or startup error (check `build_log`) - `expired` — TTL elapsed, container destroyed automatically - `stopped` — manually stopped via the API or dashboard
    - `framework` string, nullable: Auto-detected framework (e.g. `nextjs`, `vite`, `create-react-app`). `null` until detected.
    - `branch` string, required: Git branch that was built.
    - `detected_env_vars` string[], nullable: Environment variable names detected in the build output (e.g. from a missing `.env` warning). Useful for debugging misconfigured previews. Populated after first successful worker poll.
    - `build_log` string, nullable: Raw stdout/stderr from the build process. Updated in real time while building. Use `GET /api/v1/deployments/{id}/logs` for a dedicated logs endpoint.
    - `expires_at` string, date-time, nullable: ISO 8601 timestamp when the preview will be automatically destroyed. Determined by your plan TTL at the time of creation.
    - `created_at` string, date-time, required: ISO 8601 timestamp when the deployment was created.
    - `updated_at` string, date-time, required: ISO 8601 timestamp of the last status update.

## Other responses

- `401`: Missing or invalid API key.
- `404`: The requested deployment does not exist or does not belong to your workspace.
- `429`: You have exceeded the rate limit. Check the `Retry-After` header for when to resume. The limit value reflects the specific endpoint's cap (10, 60, or 120 req/60s — see Rate Limits in the overview).

---

[API](https://skmtc.dev/previewdrop/apis/previewdrop-api.md) · [All operations](https://skmtc.dev/previewdrop/apis/previewdrop-api/llms.txt) · [OpenAPI document](https://skmtc.dev/previewdrop/apis/previewdrop-api/revisions/0742e253496b?raw)