---
title: "Get a build"
method: GET
path: "/v2/builds/{id}"
tags: ["Builds"]
---

# Get a build

`GET /v2/builds/{id}`

## Request

- Base URL: `https://api.codepen.io`
- URL: `https://api.codepen.io/v2/builds/{id}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

A version's build, by the version's id: the write's `build.id`, or
`build.next_id` while the API is applying the compiler's changes (that
build is `Running` until its version is saved).

## Query parameters

- `wait` integer

## Response `200`

The build, with output `files` when it succeeded.

- Build
  - `applied_patches` BuildPatch[], required: Changes the API applied to the caller's files on the compiler's behalf.
    - `content` string, nullable, required: Set for `create` and `update`.
    - `file_id` string, nullable, required: Set for `update` and `delete`.
    - `path` string, required
    - `type` string, required: `create`, `update` or `delete`.
  - `diagnostics` BuildDiagnostic[], required: Every diagnostic of the final build.
    - `block_name` string, nullable, required
    - `code` string, nullable, required
    - `file_id` string, nullable, required
    - `message` string, required
    - `path` string, nullable, required
    - `range` FileRange, required
      - `end` FileLocation, required
        - `column` integer, required
        - `line` integer, required
        - `position` integer, nullable, required
      - `start` FileLocation, required
        - `column` integer, required
        - `line` integer, required
        - `position` integer, nullable, required
    - `scope` 'Build' | 'BuildStep' | 'File', required
    - `type` 'Error' | 'Warning' | 'Information' | 'Hint' | 'Patch', required
    - `url` string, nullable, required
  - `ended_at` string, date-time, nullable, required
  - `errors` BuildDiagnostic[], required: The diagnostics with `type` `Error`.
    - `block_name` string, nullable, required
    - `code` string, nullable, required
    - `file_id` string, nullable, required
    - `message` string, required
    - `path` string, nullable, required
    - `range` FileRange, required
      - `end` FileLocation, required
        - `column` integer, required
        - `line` integer, required
        - `position` integer, nullable, required
      - `start` FileLocation, required
        - `column` integer, required
        - `line` integer, required
        - `position` integer, nullable, required
    - `scope` 'Build' | 'BuildStep' | 'File', required
    - `type` 'Error' | 'Warning' | 'Information' | 'Hint' | 'Patch', required
    - `url` string, nullable, required
  - `files` File[]: The compiled output served under the version's `preview_url`. On the single version and build endpoints and the writes, and only when the build succeeded.
    - `bytes` integer, required
    - `content` string, nullable, required: Null for binary files, which are read from `url`.
    - `content_hash` string, required
    - `content_type` string, required: The media type the file is served with, from its extension.
    - `download_url` string, uri, nullable, required: The file's exact bytes for anyone holding the URL, on the API host (`GET /v2/pens/{id}/download/{path}`), for one hour from this response: no API key, session or Referer needed. Served as an attachment with the file's `content_type`. A new URL comes with every read; an expired one answers `403`. Null for the files of a Pen made in the classic editor.
    - `id` string, required: Stable across versions, renames and edits.
    - `is_binary` boolean, required
    - `name` string, required
    - `path` string, required
    - `url` string, uri, nullable, required: Where the file is served raw on the Pen's content domain. It follows the Pen's own access rules: a Private, Protected or Collaborators Pen needs a browser session and a Pen owned by a Free account needs a CodePen Referer, neither of which an API client has, so read files through `content` or `download_url`. Null for the files of a Pen made in the classic editor.
  - `id` string, required: The version's id, before and after the version is saved.
  - `next_id` string, nullable, required: The build applying this one's patches.
  - `patches` BuildPatch[], required: Changes the compiler still requires.
    - `content` string, nullable, required: Set for `create` and `update`.
    - `file_id` string, nullable, required: Set for `update` and `delete`.
    - `path` string, required
    - `type` string, required: `create`, `update` or `delete`.
  - `previous_id` string, nullable, required: The caller's build this one was converged from.
  - `rounds` integer, required: How many compiler builds it took, counted from the version the caller wrote.
  - `started_at` string, date-time, nullable, required
  - `status` 'Queued' | 'Running' | 'Success' | 'Failed' | 'Canceled', required: `Canceled` means changes are still required; see `patches` and `next_id`.
  - `version_id` string, nullable, required: Null while the version is still being converged.

## Other responses

- `400`: `BAD_USER_INPUT`: an invalid parameter, body, path, setting, access level or role. `field` names the argument when known, and `details` carries structured detail (the misses of `PATCH /v2/pens/{id}/files`).
- `401`: `UNAUTHENTICATED`: a missing or invalid key, a deleted owner, or a Team key for a Team that is not PRO.
- `404`: `NOT_FOUND`: no such item, or one that is not the key owner's, public or not. A path that is not an endpoint at all answers `404` with the v1 body `{ "error": "not found" }` instead.
- `429`: `RATE_LIMITED`: the owner exceeded the plan's requests in an hour, its reads today, or today's allowance of Pen or Collection creates. No `Retry-After` or rate-limit headers are sent; the body carries `retry_after_seconds`, `limit` and `reset_at`.
- `500`: `INTERNAL`: unexpected, and reported; the message is generic.

---

[API](https://skmtc.dev/codepen/apis/codepen-api.md) - [All operations](https://skmtc.dev/codepen/apis/codepen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/codepen/apis/codepen-api/revisions/108fe91e3ef5?raw)