> ## Documentation Index
> Fetch the complete documentation index at: https://www.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 deployments build-logs list

> Read a deployment's build output and page through its log entries.

> [!NOTE]
>
> Create a root key with the permissions listed on this page under **Root Keys** in the dashboard sidebar. CLI commands can instead use a session from [unkey login](https://www.unkey.com/docs/platform/cli/login.md) with the required permissions. See [Permission reference](https://www.unkey.com/docs/platform/root-keys/permissions-legacy.md) for every permission.

Retrieve the build output of a deployment as a list of log entries, in the
order the build printed them. A log entry is one chunk of build output,
and can contain several lines or part of a line.

Poll this endpoint to follow a running build:

* Send the `pagination.cursor` of the last response as `cursor`. The
  response contains only the entries after it.
* When `hasMore` is true, request again now.
* When `hasMore` is false, you have all entries so far. Wait,
  then request again with the same cursor.
* The cursor is absent only when the request had no cursor and the build
  has no entries yet.
* A response can contain fewer than `limit` entries and still have
  `hasMore: true` when the entries are large.

New entries become visible up to a few seconds after the build prints
them. To know that a build is done, check the deployment status with
[deployments get](https://www.unkey.com/docs/compute/cli/deployments/get-deployment.md). After the status is no longer `building`, request until
you get an empty response at least 5 seconds later.

When a build attempt is retried, an entry from the earlier attempt can
arrive after the cursor has moved past it, and a poll does not return it.
A request without a cursor returns it. A deployment from a prebuilt image
has no build and returns no entries. Build logs are kept for 3 months.

## Usage

```bash theme={"system"}
unkey deployments build-logs list --deployment-id=<deployment-id> [flags]
```

## Flags

**--cursor** `string`

Pagination cursor from a previous response to fetch the entries after it. Omit it to start at the first entry of the build.

**--deployment-id** `string` *required*

Identifies the deployment by its unique ID or slug. Accepts a prefixed deployment ID such as `d_1234abcd` or a slug.

**--limit** `integer`

Maximum number of log entries to return. A response can contain fewer entries and still have `hasMore: true` when the entries are large. Range: 1 to 500. The API defaults to 100 when omitted.

**--step-id** `string`

Return only the log entries of this build step. Use the `stepId` of an entry from a previous response. An unknown step returns no entries. Omit this field to return the entries of every step.

### Shared flags

These flags control authentication, requests, and output. [CLI output and shared flags](https://www.unkey.com/docs/platform/cli/output-and-flags.md) describes them in full.

**--body** `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](https://www.unkey.com/docs/platform/cli/output-and-flags.md#send-a-raw-body).

**--root-key** `string`

Root key used for the request. Falls back to `UNKEY_ROOT_KEY`, then stored credentials, including a CLI session. See [CLI authentication](https://www.unkey.com/docs/platform/cli/authentication.md) for the full precedence order.

**--api-url** `string` (default: [https://api.unkey.com](https://api.unkey.com))

Base URL of the API. Falls back to `UNKEY_API_BASE_URL`. You don't normally need to set it.

**--config** `string` (default: \~/.unkey/config.toml)

Path of the TOML config file. Falls back to `UNKEY_CONFIG`. An explicit `--config` takes precedence over a stored CLI session. Browser login stores a session, not a root key in this file. See [CLI authentication](https://www.unkey.com/docs/platform/cli/authentication.md).

**--output** `enum` (default: human)

Use `human` (default) for name-first summary tables and labeled details, or `json` for the unchanged full response envelope, including all fields and pagination. Terminal tables use relative timestamps and may shorten display names and descriptions, but never identifiers, slugs, or credentials. Redirected human output keeps complete values and uses RFC3339 UTC timestamps. Falls back to `UNKEY_OUTPUT`; other values are rejected. `--json` also selects JSON output. Add `--debug` to print the request ID to stderr. See [Output formats](https://www.unkey.com/docs/platform/cli/output-and-flags.md#output-formats).

**--debug** `boolean`

Print the successful response's request ID to stderr, separate from stdout.

**--json** `boolean`

Print the full response as JSON. Takes precedence over a valid `--output` or `UNKEY_OUTPUT` value.

## Required permissions

Your root key must have the following permission:

* `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>/buildLogs#read`

See [Root key permissions](https://www.unkey.com/docs/platform/root-keys/permissions.md).

## Examples

```bash theme={"system"}
unkey deployments build-logs list --deployment-id=d_1234abcd
```

```bash theme={"system"}
unkey deployments build-logs list --deployment-id=d_1234abcd --cursor=1704067201000001 --limit=50
```

Send the request body as JSON:

```bash theme={"system"}
unkey deployments build-logs list --body='{"deploymentId":"d_1234abcd","limit":50}'
```

## API endpoint

The command calls `POST /v2/deployments.listBuildLogs` and prints its response. See the [endpoint definition](https://github.com/unkeyed/unkey/blob/main/svc/api/openapi/spec/paths/v2/deployments/listBuildLogs/index.yaml) for the HTTP contract. Request fields use camelCase in `--body`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.