You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys. See Permission reference for every permission.
--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
Flags
string
App ID or slug to filter by. Requires
--project.string
Pagination cursor from a previous response.
string
Environment ID or slug to filter by. Requires
--project and --app.integer
Maximum deployments per page, between 1 and 100. The API uses 100 when the flag is omitted.
string
Project ID or slug to filter by.
string[]
Comma-separated lifecycle statuses to include.
Shared flags
Everyunkey api command accepts these; CLI output and shared flags describes them in full.
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.
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.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.string
default:"~/.unkey/config.toml"
Path of the TOML file that
unkey auth login writes. Falls back to UNKEY_CONFIG.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.Required permissions
Your root key needsenvironment.*.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 for the full catalog.
Examples
Deployments of one environment:API endpoint
The command callsPOST /v2/deployments.listDeployments and prints its response. The request fields carry the same names as the flags in camelCase, which is the shape --body expects.