UNunkeyed
deployments

List deployments

Changed on

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

Filter by project, app, environment, lifecycle status, git branch, and creation time. All filters are optional; with none set, every deployment in the workspace is returned. Filters nest: app requires project, and environment and branch require 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 this permission:

  • unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/*#read (use * for every level you do not filter by)

The permission must cover every deployment the filters select: a grant on one environment is not sufficient for a request that spans more than that environment.

post/v2/deployments.listDeployments

Request

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/deployments.listDeployments
  • Auth
    HTTP bearer

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.

branchstring[]

Restrict results to deployments built from any of the given git branches. Requires project and app to also be set. Omit or pass an empty list to return deployments from every branch.

startTimeinteger

Return only deployments created at or after this unix timestamp in milliseconds (inclusive).

endTimeinteger

Return only deployments created before this unix timestamp in milliseconds (exclusive). Must be later than startTime when both are set.

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"
  ],
  "branch": [
    "main",
    "feature/checkout"
  ],
  "startTime": 1704067200000,
  "endTime": 1704672000000
}

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",
        "commitMessage": "fix: retry on 429",
        "commitTimestamp": 1704067100000,
        "author": {
          "handle": "octocat",
          "avatarUrl": "https://avatars.githubusercontent.com/u/583231"
        },
        "prNumber": 412,
        "forkRepository": "octocat/payments-api"
      },
      "docker": {
        "image": "ghcr.io/acme/api:v1.2.3",
        "resolvedImage": "ghcr.io/acme/api@sha256:3f1d9c0b7e2a4c8f5b6d1e0a9c8b7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a"
      },
      "trigger": {
        "via": "github",
        "actor": {
          "type": "github",
          "id": "octocat"
        }
      },
      "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."
      },
      "issues": [
        {
          "type": "crash_loop",
          "time": 1704067260000,
          "message": "Your app used more memory than its limit and keeps stopping, so Unkey waits longer before each restart. Check its memory usage, or raise the limit.",
          "meta": {
            "reason": "out_of_memory",
            "exitCode": 137,
            "restartCount": 12
          }
        }
      ],
      "finishedAt": 1704067260000,
      "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
  }
}

Changes

  • 6db5ffb0a909Revision changes
    • info

      added the required property // to the response with the status

  • 1da49cb46e57Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the required property // to the response with the status