Sign in

v66

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB
deployments

List deployments

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.

post/v2/deployments.listDeployments

Request body

projectstring

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

appstring

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

environmentstring

Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

statusDeploymentStatus[]

Restrict results to deployments in any of the given lifecycle statuses. Omit to return deployments in every status.

limitinteger

Maximum number of deployments to return per request. Balance between response size and number of pagination calls needed.

cursorstring

Pagination cursor from a previous response to fetch the next page. Use when hasMore: true in the previous response.

Example request

{
  "project": "proj_1234abcd",
  "app": "proj_1234abcd",
  "environment": "proj_1234abcd",
  "status": [
    "ready",
    "failed"
  ]
}

Response

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

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "id": "d_1234abcd",
      "status": "ready",
      "isCurrent": true,
      "environment": "production",
      "app": "payments-api",
      "project": "acme",
      "git": {
        "commitSha": "9f2c1a7d3b",
        "branch": "main"
      },
      "docker": {
        "image": "ghcr.io/acme/api:v1.2.3"
      },
      "availableActions": [
        "stop"
      ],
      "regions": [
        "us-east-1",
        "eu-west-1"
      ],
      "error": {
        "code": "no_schedulable_regions",
        "step": "deploying",
        "message": "No schedulable regions configured. Please configure at least one schedulable region before deploying."
      },
      "domains": [
        "kebap-app.unkey.app"
      ],
      "runtime": {
        "vCpus": 0.25,
        "memoryMib": 256,
        "port": 8080,
        "command": [
          "node",
          "server.js"
        ],
        "shutdownSignal": "SIGTERM",
        "upstreamProtocol": "http1",
        "healthcheck": {
          "method": "GET",
          "path": "/healthz",
          "intervalSeconds": 10,
          "timeoutSeconds": 2,
          "failureThreshold": 3,
          "initialDelaySeconds": 5
        }
      },
      "createdAt": 1704067200000,
      "updatedAt": 1704153600000
    }
  ],
  "pagination": {
    "cursor": "eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ==",
    "hasMore": true
  }
}