---
title: "Build"
description: "The `Build` entity."
section: "Reference"
group: "Types"
order: 38
---

## Definition

```ts
interface Build {
  id: string;
  workspaceId: string;
  entityId: string;
  sequenceNumber: number;
  status: "pending" | "failed" | "running" | "completed" | "cancelled";
  trigger: "manual" | "auto" | "redeploy";
  sourceEventId: string | null;
  error: string | null;
  metadata: Record<string, unknown> | null;
  createdBy: string | null;
  startedAt: string | null;
  completedAt: string | null;
  createdAt: string;
}
```

## Fields

| Field            | Type                                                               | Notes                                                                                     |
| ---------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `id`             | `string`                                                           | `readonly` `required`                                                                     |
| `workspaceId`    | `string`                                                           | `required` — Workspace that owns this build.                                              |
| `entityId`       | `string`                                                           | `required` — Prefixed ID of the entity being built (e.g. app, function, element version). |
| `sequenceNumber` | `number`                                                           | `required` — Monotonically-increasing build number for the target entity.                 |
| `status`         | `"pending" \| "failed" \| "running" \| "completed" \| "cancelled"` | `required` — Build lifecycle (queued, running, succeeded, failed, cancelled).             |
| `trigger`        | `"manual" \| "auto" \| "redeploy"`                                 | `required` — What initiated the build (user action, event, schedule, etc.).               |
| `sourceEventId`  | `string \| null`                                                   | `required` — ID of the event that triggered the build, when applicable.                   |
| `error`          | `string \| null`                                                   | `required` — Error message when the build failed, otherwise null.                         |
| `metadata`       | `Record<string, unknown> \| null`                                  | `required` — Free-form build metadata (durations, artifacts, etc.).                       |
| `createdBy`      | `string \| null`                                                   | `required` — User who started the build; null for system-triggered builds.                |
| `startedAt`      | `string \| null`                                                   | `required` — ISO-8601 timestamp when the build began executing.                           |
| `completedAt`    | `string \| null`                                                   | `required` — ISO-8601 timestamp when the build finished.                                  |
| `createdAt`      | `string`                                                           | `readonly` `required` — ISO-8601 timestamp of creation.                                   |