---
title: "BuildStep"
description: "The `BuildStep` entity."
section: "Reference"
group: "Types"
order: 41
---

## Definition

```ts
interface BuildStep {
  id: string;
  buildId: string;
  name: string;
  status: "pending" | "failed" | "running" | "completed" | "skipped";
  order: number;
  error: string | null;
  log: string | null;
  metadata: Record<string, unknown> | null;
  startedAt: string | null;
  completedAt: string | null;
  createdAt: string;
}
```

## Fields

| Field         | Type                                                             | Notes                                                                    |
| ------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `id`          | `string`                                                         | `readonly` `required`                                                    |
| `buildId`     | `string`                                                         | `required` — Build this step belongs to.                                 |
| `name`        | `string`                                                         | `required` — Human-readable step name (e.g. 'install', 'compile').       |
| `status`      | `"pending" \| "failed" \| "running" \| "completed" \| "skipped"` | `required` — Step status (pending, running, succeeded, failed, skipped). |
| `order`       | `number`                                                         | `required` — Zero-based ordering index for displaying steps in sequence. |
| `error`       | `string \| null`                                                 | `required` — Error message when the step failed, otherwise null.         |
| `log`         | `string \| null`                                                 | `required` — Captured log output for this step, if any.                  |
| `metadata`    | `Record<string, unknown> \| null`                                | `required` — Free-form step metadata (timings, artifact IDs, etc.).      |
| `startedAt`   | `string \| null`                                                 | `required` — ISO-8601 timestamp when the step began executing.           |
| `completedAt` | `string \| null`                                                 | `required` — ISO-8601 timestamp when the step finished.                  |
| `createdAt`   | `string`                                                         | `readonly` `required` — ISO-8601 timestamp of creation.                  |