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

# workflows runs steps

> List the individual execution steps of a workflow run.

List the individual execution steps of a workflow run as a flat array, with optional filters by node, status, and step type. Where [`clay workflows runs get`](/cli/reference/workflows-runs-get) gives a node-level summary, this command exposes every step — including map/reduce entry steps — and their raw input/output payloads.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay workflows runs steps <workflowId> <runId> [--node-id <id>] [--status <status>] [--parent-only | --entries-only]
```

## Arguments

| Argument     | Description                              |
| ------------ | ---------------------------------------- |
| `workflowId` | Workflow id, e.g. `wf_abc123`. Required. |
| `runId`      | Run id, e.g. `wfr_xyz789`. Required.     |

## Flags

| Flag                | Description                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------- |
| `--node-id <id>`    | Only steps for this workflow node id.                                                                |
| `--status <status>` | Only steps with this status. One of `pending`, `active`, `waiting`, `paused`, `completed`, `failed`. |
| `--parent-only`     | Exclude map/reduce entry steps (keeps `base` and `map_reduce` steps).                                |
| `--entries-only`    | Only map/reduce entry steps.                                                                         |

`--parent-only` and `--entries-only` are mutually exclusive.

## Output

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "stepId": "step_1",
      "nodeId": "node_3",
      "stepType": "map_reduce",
      "status": "completed",
      "nodeName": "Enrich companies",
      "isAsync": true,
      "startedAt": "2026-06-01T00:01:00Z",
      "completedAt": "2026-06-01T00:04:00Z",
      "mapIndex": 0,
      "mapKey": "clay.com",
      "entryMetadata": {},
      "mapReduceStats": {},
      "stepInputs": {},
      "stepOutputs": {}
    }
  ]
}
```

| Field                   | Type           | Description                                                                       |
| ----------------------- | -------------- | --------------------------------------------------------------------------------- |
| `data[].stepId`         | string         | Step id.                                                                          |
| `data[].nodeId`         | string         | Workflow node the step belongs to.                                                |
| `data[].stepType`       | enum           | `base`, `map_reduce`, or `entry`. See the step type values below.                 |
| `data[].status`         | enum           | `pending`, `active`, `waiting`, `paused`, `completed`, or `failed`.               |
| `data[].statusDetail`   | string         | Extra status context, when present.                                               |
| `data[].nodeName`       | string \| null | Node display name, or `null`.                                                     |
| `data[].isAsync`        | boolean        | Whether the step runs asynchronously.                                             |
| `data[].startedAt`      | string \| null | When the step started, or `null`.                                                 |
| `data[].completedAt`    | string \| null | When the step completed, or `null`.                                               |
| `data[].errors`         | string\[]      | Error messages, when present.                                                     |
| `data[].mapIndex`       | number         | Index within a map/reduce fan-out, on entry steps.                                |
| `data[].mapKey`         | string         | Key within a map/reduce fan-out, on entry steps.                                  |
| `data[].entryMetadata`  | object         | Free-form server payload; its inner shape varies and is not part of the contract. |
| `data[].mapReduceStats` | object         | Fan-out statistics, on map/reduce steps.                                          |
| `data[].stepInputs`     | object \| null | Free-form execution input payload; inner shape varies by node type.               |
| `data[].stepOutputs`    | object \| null | Free-form execution output payload; inner shape varies by node type.              |

`stepInputs`, `stepOutputs`, and `entryMetadata` are free-form execution payloads. Their inner shape varies by node type and is not part of the CLI contract.

### Step type values

| Value        | Description                                                                                                    |
| ------------ | -------------------------------------------------------------------------------------------------------------- |
| `base`       | A regular single-execution step.                                                                               |
| `map_reduce` | A parent step that fans out over a data list.                                                                  |
| `entry`      | A single slot within a map/reduce fan-out. `--entries-only` selects only these; `--parent-only` excludes them. |

### Archived runs

If the server returns an archived record for an old run, the output is `{ "runId": <string>, "archived": true, "logUrl": <string> }` instead. Today the server reports archived runs as `not_found`, so expect that error for old runs.

## Errors

| Code               | Exit | Notes                                                                                         |
| ------------------ | ---- | --------------------------------------------------------------------------------------------- |
| `validation_error` | 2    | `--parent-only` and `--entries-only` are mutually exclusive.                                  |
| `not_found`        | 6    | No run with that id under that workflow, or the run's details have been archived server-side. |
| `auth_forbidden`   | 3    | The API key lacks the `terracotta:cli` scope.                                                 |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay workflows runs steps wf_abc123 wfr_xyz789 --status failed
clay workflows runs steps wf_abc123 wfr_xyz789 | jq '.data[] | select(.errors) | {stepId, errors}'
clay workflows runs steps wf_abc123 wfr_xyz789 --parent-only | jq -r '.data[] | "\(.nodeName)\t\(.status)"'
clay workflows runs steps wf_abc123 wfr_xyz789 --node-id node_3 --entries-only | jq '.data | length'
```