--- title: "List build logs" method: POST path: "/v2/deployments.listBuildLogs" tags: ["deployments"] --- # List build logs `POST /v2/deployments.listBuildLogs` ## Request - Base URL: `https://api.unkey.com` - URL: `https://api.unkey.com/v2/deployments.listBuildLogs` - Auth: HTTP bearer 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 `getDeployment`. 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. **Required Permissions** Your root key must have the following permission: - `unkey:v1::projects//apps//environments//deployments//buildLogs#read` ## Request body - V2DeploymentsListBuildLogsRequestBody: Retrieve the build log entries of a deployment. Get the deployment id from `createDeployment` or `listDeployments`. - `deploymentId` string, required: Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug. - `stepId` 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. - `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. - `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. ## Response `200` Successfully retrieved the build log entries. - V2DeploymentsListBuildLogsResponseBody - `meta` Meta, 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. - `requestId` string, required: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance. - `data` BuildLogEntry[], required: The log entries, in the order the build printed them. - `time` integer, required: When the build printed the entry, in Unix epoch milliseconds. - `stepId` string, required: The build step that printed the entry. Pass it as `stepId` to return only this step's entries. - `step` string, required: The name of the build step, such as `[3/7] RUN npm ci`, cut to 256 characters. Empty when the step name is not known. - `output` 'stdout' | 'stderr', required: The output stream a build log entry was printed to. Many tools write progress and warnings to `stderr`, so `stderr` does not mean that the step failed. - `message` string, required: The text the build printed. One entry can contain several lines or part of a line. - `pagination` Pagination, required: Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination. - `cursor` string: Opaque pagination token for retrieving the next page of results. Include this exact value in the cursor field of subsequent requests. Cursors are temporary and may expire after extended periods. - `hasMore` boolean, required: Indicates whether additional results exist beyond this page. When true, use the cursor to fetch the next page. When false, you have reached the end of the result set. ## Other responses - `400`: Bad request - `401`: Unauthorized - `403`: Forbidden - Your root key can read the deployment but lacks permission to read its build logs. - `404`: Not Found - The requested deployment does not exist in your workspace - `429`: Too Many Requests - `500`: Internal server error ## Changes - **2026-10-27** `6ed4b9847395`: 1 info - added the non-success response with the status `403` - **2026-10-06** `f3509ced036f`: 1 info - endpoint added [Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/deployments.listBuildLogs/post.md) --- [API](https://skmtc.dev/unkeyed/apis/unkey-api.md) - [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)