List deployments

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

deployments.listDeployments

Go (SDK)

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v3"
	"github.com/unkeyed/sdks/api/go/v3/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Deployments.ListDeployments(ctx, components.V2DeploymentsListDeploymentsRequestBody{
        Project: unkey.Pointer("payments-service"),
        App: unkey.Pointer("payments-api"),
        Branch: []string{
            "main",
            "feature/checkout",
        },
        StartTime: unkey.Pointer[int64](1704067200000),
        EndTime: unkey.Pointer[int64](1704672000000),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2DeploymentsListDeploymentsResponseBody != nil {
        for {
            // handle items

            res, err = res.Next()

            if err != nil {
                // handle error
            }

            if res == nil {
                break
            }
        }
    }
}

from unkey.py import Unkey, models


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.deployments.list_deployments(project="payments-service", app="payments-api", environment="proj_1234abcd", status=[
        models.DeploymentStatus.READY,
        models.DeploymentStatus.FAILED,
    ], branch=[
        "main",
        "feature/checkout",
    ], start_time=1704067200000, end_time=1704672000000, limit=100)

    while res is not None:
        # Handle items

        res = res.next()

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.deployments.listDeployments({
    project: "payments-service",
    app: "payments-api",
    branch: [
      "main",
      "feature/checkout",
    ],
    startTime: 1704067200000,
    endTime: 1704672000000,
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

curl --request POST \
  --url https://api.unkey.com/v2/deployments.listDeployments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app": "payments-api",
  "branch": [
    "main",
    "feature/checkout"
  ],
  "endTime": 1704672000000,
  "project": "payments-service",
  "startTime": 1704067200000
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    app: 'payments-api',
    branch: ['main', 'feature/checkout'],
    endTime: 1704672000000,
    project: 'payments-service',
    startTime: 1704067200000
  })
};

fetch('https://api.unkey.com/v2/deployments.listDeployments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/deployments.listDeployments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'app' => 'payments-api',
    'branch' => [
        'main',
        'feature/checkout'
    ],
    'endTime' => 1704672000000,
    'project' => 'payments-service',
    'startTime' => 1704067200000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/deployments.listDeployments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"app\": \"payments-api\",\n  \"branch\": [\n    \"main\",\n    \"feature/checkout\"\n  ],\n  \"endTime\": 1704672000000,\n  \"project\": \"payments-service\",\n  \"startTime\": 1704067200000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/deployments.listDeployments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"app\": \"payments-api\",\n  \"branch\": [\n    \"main\",\n    \"feature/checkout\"\n  ],\n  \"endTime\": 1704672000000,\n  \"project\": \"payments-service\",\n  \"startTime\": 1704067200000\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "createdAt": 1704153600000,
      "id": "dep_1234abcd",
      "runtime": {
        "command": [
          "node",
          "server.js"
        ],
        "cpuMillicores": 250,
        "memoryMib": 256,
        "port": 8080,
        "shutdownSignal": "SIGTERM",
        "storageMib": 0,
        "upstreamProtocol": "http1"
      },
      "status": "ready"
    },
    {
      "createdAt": 1704067200000,
      "id": "dep_5678efgh",
      "runtime": {
        "command": [],
        "cpuMillicores": 250,
        "memoryMib": 256,
        "port": 8080,
        "shutdownSignal": "SIGTERM",
        "storageMib": 0,
        "upstreamProtocol": "http1"
      },
      "status": "failed"
    }
  ],
  "meta": {
    "requestId": "req_1234abcd"
  },
  "pagination": {
    "hasMore": false
  }
}

{
  "error": {
    "detail": "The 'environment' filter requires both 'project' and 'app' to be set.",
    "status": 400,
    "title": "Bad Request",
    "type": "validation-error"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "error": {
    "detail": "You cannot read deployments in the requested scope. Grant read on projects/<project>/apps/<app>/environments/<environment>/deployments/* with * for every level you do not filter by.",
    "status": 403,
    "title": "Forbidden",
    "type": "forbidden"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "error": {
    "detail": "The requested project does not exist.",
    "status": 404,
    "title": "Not Found",
    "type": "not-found"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

Authorizations

Authorization

string

header

required

Unkey uses bearer tokens for authentication. Public integrations use root keys, while the dashboard proxy uses short-lived JWTs. To authenticate, include the token in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Legacy permissions use tuple strings like api.*.create_key; resource permissions use Unkey Resource Names plus actions, like unkey:v1:ws_123:keyspaces/*#create_key. Security best practices:

Keep root keys secure and never expose them in client-side code
Use different root keys for different environments
Rotate keys periodically, especially after team member departures
Create keys with minimal necessary permissions following least privilege principle
Monitor key usage with audit logs.

Body

application/json

Filter deployments within a workspace. All filters are optional; with none set, every deployment in the workspace is returned, newest first.

project

string

Restrict results to a single project, identified by its ID or slug. Required when filtering by app, environment, or branch.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

app

string

Restrict results to a single app, identified by its ID or slug. Requires project to also be set.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

environment

string

Restrict results to a single environment, identified by its ID or slug. Requires project and app to also be set.

Required string length: 3 - 255

Pattern: ^[a-zA-Z0-9_-]+$

Example:

"proj_1234abcd"

status

enum<string>[]

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

Maximum array length: 13

Current lifecycle status of the deployment. Poll until it reaches a terminal state: ready (serving), failed, skipped, superseded, stopped, or cancelled.

Available options:

pending,

starting,

building,

deploying,

network,

finalizing,

ready,

failed,

skipped,

awaiting_approval,

stopped,

superseded,

cancelled

Example:

["ready", "failed"]

branch

string[]

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.

Maximum array length: 50

Required string length: 1 - 256

Example:

["main", "feature/checkout"]

startTime

integer<int64>

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

Required range: 0 <= x <= 9223372036854776000

Example:

1704067200000

endTime

integer<int64>

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

Required range: 0 <= x <= 9223372036854776000

Example:

1704672000000

limit

integer

default:100

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

Required range: 1 <= x <= 100

cursor

string

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

Response

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

meta

object

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.

Show child attributes

data

object[]

required

Array of deployments, ordered newest first.

Maximum array length: 100

Show child attributes

pagination

object

required

Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.

Show child attributes

⌘I

Go (SDK)

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v3"
	"github.com/unkeyed/sdks/api/go/v3/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Deployments.ListDeployments(ctx, components.V2DeploymentsListDeploymentsRequestBody{
        Project: unkey.Pointer("payments-service"),
        App: unkey.Pointer("payments-api"),
        Branch: []string{
            "main",
            "feature/checkout",
        },
        StartTime: unkey.Pointer[int64](1704067200000),
        EndTime: unkey.Pointer[int64](1704672000000),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2DeploymentsListDeploymentsResponseBody != nil {
        for {
            // handle items

            res, err = res.Next()

            if err != nil {
                // handle error
            }

            if res == nil {
                break
            }
        }
    }
}

from unkey.py import Unkey, models


with Unkey(
    root_key="<YOUR_BEARER_TOKEN_HERE>",
) as unkey:

    res = unkey.deployments.list_deployments(project="payments-service", app="payments-api", environment="proj_1234abcd", status=[
        models.DeploymentStatus.READY,
        models.DeploymentStatus.FAILED,
    ], branch=[
        "main",
        "feature/checkout",
    ], start_time=1704067200000, end_time=1704672000000, limit=100)

    while res is not None:
        # Handle items

        res = res.next()

import { Unkey } from "@unkey/api";

const unkey = new Unkey({
  rootKey: process.env["UNKEY_ROOT_KEY"] ?? "",
});

async function run() {
  const result = await unkey.deployments.listDeployments({
    project: "payments-service",
    app: "payments-api",
    branch: [
      "main",
      "feature/checkout",
    ],
    startTime: 1704067200000,
    endTime: 1704672000000,
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

curl --request POST \
  --url https://api.unkey.com/v2/deployments.listDeployments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app": "payments-api",
  "branch": [
    "main",
    "feature/checkout"
  ],
  "endTime": 1704672000000,
  "project": "payments-service",
  "startTime": 1704067200000
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    app: 'payments-api',
    branch: ['main', 'feature/checkout'],
    endTime: 1704672000000,
    project: 'payments-service',
    startTime: 1704067200000
  })
};

fetch('https://api.unkey.com/v2/deployments.listDeployments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unkey.com/v2/deployments.listDeployments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'app' => 'payments-api',
    'branch' => [
        'main',
        'feature/checkout'
    ],
    'endTime' => 1704672000000,
    'project' => 'payments-service',
    'startTime' => 1704067200000
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.post("https://api.unkey.com/v2/deployments.listDeployments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"app\": \"payments-api\",\n  \"branch\": [\n    \"main\",\n    \"feature/checkout\"\n  ],\n  \"endTime\": 1704672000000,\n  \"project\": \"payments-service\",\n  \"startTime\": 1704067200000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unkey.com/v2/deployments.listDeployments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"app\": \"payments-api\",\n  \"branch\": [\n    \"main\",\n    \"feature/checkout\"\n  ],\n  \"endTime\": 1704672000000,\n  \"project\": \"payments-service\",\n  \"startTime\": 1704067200000\n}"

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "createdAt": 1704153600000,
      "id": "dep_1234abcd",
      "runtime": {
        "command": [
          "node",
          "server.js"
        ],
        "cpuMillicores": 250,
        "memoryMib": 256,
        "port": 8080,
        "shutdownSignal": "SIGTERM",
        "storageMib": 0,
        "upstreamProtocol": "http1"
      },
      "status": "ready"
    },
    {
      "createdAt": 1704067200000,
      "id": "dep_5678efgh",
      "runtime": {
        "command": [],
        "cpuMillicores": 250,
        "memoryMib": 256,
        "port": 8080,
        "shutdownSignal": "SIGTERM",
        "storageMib": 0,
        "upstreamProtocol": "http1"
      },
      "status": "failed"
    }
  ],
  "meta": {
    "requestId": "req_1234abcd"
  },
  "pagination": {
    "hasMore": false
  }
}

{
  "error": {
    "detail": "The 'environment' filter requires both 'project' and 'app' to be set.",
    "status": 400,
    "title": "Bad Request",
    "type": "validation-error"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "error": {
    "detail": "You cannot read deployments in the requested scope. Grant read on projects/<project>/apps/<app>/environments/<environment>/deployments/* with * for every level you do not filter by.",
    "status": 403,
    "title": "Forbidden",
    "type": "forbidden"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "error": {
    "detail": "The requested project does not exist.",
    "status": 404,
    "title": "Not Found",
    "type": "not-found"
  },
  "meta": {
    "requestId": "req_1234abcd"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

{
  "meta": {
    "requestId": "req_123"
  },
  "error": {
    "detail": "Property foo is required but is missing.",
    "status": 404,
    "title": "Not Found",
    "type": "https://unkey.com/docs/errors/unkey/resource/not_found"
  }
}

Projects

Apps

Environments

Deployments

Domains

Gateway

GitHub

Analytics

List deployments

Authorizations

Body

Response