---
title: "List deployments"
method: GET
path: "/api/v1/deployments"
tags: ["Deployments"]
---

# List deployments

`GET /api/v1/deployments`

## Request

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

Returns up to 50 recent deployments for your workspace, ordered by creation time (newest first). Use `branch`, `projectId`, or `status` query parameters to filter results — especially useful in CI to check if a deployment for a given branch already exists.

## Query parameters

- `branch` string
- `projectId` string, uuid
- `status` 'queued' | 'building' | 'deploying' | 'ready' | 'failed' | 'stopped' | 'expired'

## Response `200`

OK

- DeploymentList
  - `deployments` Deployment[], required: Up to 50 deployments, ordered by creation time (newest first).
    - `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.
- `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).
- `500`: Internal server error (database failure).

---

[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)