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

# Builds

> List, fetch, download artifacts.

## `GET /builds`

List builds across the org, with filters.

Query params:

| Param                   | Description                                              |
| ----------------------- | -------------------------------------------------------- |
| `projectId`             | Filter to one project                                    |
| `buildSettingId`        | Filter to one build setting                              |
| `status`                | `pending`, `running`, `complete`, `failed`, `superseded` |
| `platform`, `buildType` | Filter                                                   |
| `branch`                | Filter                                                   |
| `limit`, `cursor`       | Pagination                                               |

Response:

```json theme={null}
{
  "items": [
    {
      "id": "...",
      "projectId": "...",
      "buildSettingId": "...",
      "status": "complete",
      "platform": "Win64",
      "buildType": "Development",
      "branch": "main",
      "commit": "a1b2c3d...",
      "commitMessage": "Fix lighting in level 3",
      "ueVersion": "5.4",
      "triggeredBy": "user:...",
      "createdAt": "...",
      "finishedAt": "...",
      "durationMs": 763000
    }
  ],
  "nextCursor": "..."
}
```

## `GET /builds/:id`

Build detail, including the most recent log lines.

## `GET /builds/:id/download`

Get a signed URL for the artifact tarball.

```bash theme={null}
curl https://api.buildpixel.io/builds/$BUILD_ID/download \
  -H "Authorization: Bearer $TOKEN"
```

Response:

```json theme={null}
{
  "url": "https://...",
  "expiresAt": "...",
  "sizeBytes": 4823482910,
  "checksumMd5": "a1b2..."
}
```

The URL is good for 24 hours. Refetch when needed.

`404 not_found` if the build never produced an artifact (failed before stage) or the artifact has been deleted by retention.