> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Unkey is two separate products. Compute builds, deploys, and runs apps behind a gateway. API Management issues API keys, enforces rate limits, manages identities and permissions, and reports usage. Say which product a page belongs to; a reader can use either without the other.
> Every Unkey API endpoint is an HTTP POST to https://api.unkey.com/v2/{service}.{procedure} with a root key in the Authorization: Bearer header. Root keys are workspace scoped.
> Error codes have the form err:{system}:{category}:{specific} and each has a page at /errors/{system}/{category}/{specific}.
> The word environment means production or preview in Compute. Rate limiting has four meanings on this site; the glossary lists them.

# unkey api deployments list-deployments

> List deployments newest first, filtered by app or status.

<Note>
  You need a root key with the permissions listed on this page. Create one in the dashboard under **Settings > Root Keys**. See [Permission reference](/docs/platform/root-keys/permissions-legacy) for every permission.
</Note>

List deployments in the workspace, newest first. All filters are optional. With none set, every deployment in the workspace is returned. Filters nest: `--app` requires `--project`, and `--environment` requires both. When `pagination.hasMore` is true, pass `pagination.cursor` back with `--cursor`.

`--status` takes a comma-separated list of statuses from `pending`, `starting`, `building`, `deploying`, `network`, `finalizing`, `ready`, `failed`, `skipped`, `awaiting_approval`, `stopped`, `superseded`, and `cancelled`.

## Usage

```bash theme={"system"}
unkey api deployments list-deployments [--project=<project> [--app=<app> [--environment=<environment>]]] [--status=<status>,...] [--limit=<n>] [--cursor=<cursor>]
```

## Flags

<ParamField body="--app" type="string">
  App ID or slug to filter by. Requires `--project`.
</ParamField>

<ParamField body="--cursor" type="string">
  Pagination cursor from a previous response.
</ParamField>

<ParamField body="--environment" type="string">
  Environment ID or slug to filter by. Requires `--project` and `--app`.
</ParamField>

<ParamField body="--limit" type="integer">
  Maximum deployments per page, between 1 and 100. The API uses 100 when the flag is omitted.
</ParamField>

<ParamField body="--project" type="string">
  Project ID or slug to filter by.
</ParamField>

<ParamField body="--status" type="string[]">
  Comma-separated lifecycle statuses to include.
</ParamField>

### Shared flags

Every `unkey api` command accepts these; [CLI output and shared flags](/docs/platform/cli/output-and-flags) describes them in full.

<ParamField body="--body" type="string">
  A JSON document sent as the request body instead of building it from the flags above. It is mutually exclusive with the request-building flags, and unknown fields are rejected locally. See [Send a raw body](/docs/platform/cli/output-and-flags#send-a-raw-body).
</ParamField>

<ParamField body="--root-key" type="string">
  Root key for the request. Falls back to `UNKEY_ROOT_KEY`, then to the config file written by `unkey auth login`. See [CLI authentication](/docs/platform/cli/authentication).
</ParamField>

<ParamField body="--api-url" type="string" default="https://api.unkey.com">
  Base URL of the API. Falls back to `UNKEY_API_BASE_URL`. You don't normally need to set it.
</ParamField>

<ParamField body="--config" type="string" default="~/.unkey/config.toml">
  Path of the TOML file that `unkey auth login` writes. Falls back to `UNKEY_CONFIG`.
</ParamField>

<ParamField body="--output" type="string">
  Output format. Falls back to `UNKEY_OUTPUT`. Set `json` to print the full response envelope (`meta` and `data`) for piping; any other value prints the request ID followed by `data`.
</ParamField>

## Required permissions

Your root key needs `environment.*.read_deployment`.

A grant for a single environment isn't enough, because the list spans environments.

Without a matching permission the API answers 403 and the CLI prints `Permission denied:` followed by the detail. See [Root key permissions](/docs/platform/root-keys/permissions) for the full catalog.

## Examples

Deployments of one environment:

```bash theme={"system"}
unkey api deployments list-deployments --project=payments --app=payments-api --environment=production
```

Recent successes and failures across the workspace:

```bash theme={"system"}
unkey api deployments list-deployments --status=ready,failed --limit=25
```

## API endpoint

The command calls [`POST /v2/deployments.listDeployments`](/docs/compute/api-reference/deployments/list-deployments) and prints its response. The request fields carry the same names as the flags in camelCase, which is the shape `--body` expects.