Skip to main content
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 gives a node-level summary, this command exposes every step — including map/reduce entry steps — and their raw input/output payloads. 
clay workflows runs steps <workflowId> <runId> [--node-id <id>] [--status <status>] [--parent-only | --entries-only]

​
Arguments

ArgumentDescription
workflowIdWorkflow id, e.g. wf_abc123. Required.
runIdRun id, e.g. wfr_xyz789. Required.

​
Flags

FlagDescription
--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-onlyExclude map/reduce entry steps (keeps base and map_reduce steps).
--entries-onlyOnly map/reduce entry steps.
--parent-only and --entries-only are mutually exclusive.

​
Output

{
  "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": {}
    }
  ]
}
FieldTypeDescription
data[].stepIdstringStep id.
data[].nodeIdstringWorkflow node the step belongs to.
data[].stepTypeenumbase, map_reduce, or entry. See the step type values below.
data[].statusenumpending, active, waiting, paused, completed, or failed.
data[].statusDetailstringExtra status context, when present.
data[].nodeNamestring | nullNode display name, or null.
data[].isAsyncbooleanWhether the step runs asynchronously.
data[].startedAtstring | nullWhen the step started, or null.
data[].completedAtstring | nullWhen the step completed, or null.
data[].errorsstring[]Error messages, when present.
data[].mapIndexnumberIndex within a map/reduce fan-out, on entry steps.
data[].mapKeystringKey within a map/reduce fan-out, on entry steps.
data[].entryMetadataobjectFree-form server payload; its inner shape varies and is not part of the contract.
data[].mapReduceStatsobjectFan-out statistics, on map/reduce steps.
data[].stepInputsobject | nullFree-form execution input payload; inner shape varies by node type.
data[].stepOutputsobject | nullFree-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

ValueDescription
baseA regular single-execution step.
map_reduceA parent step that fans out over a data list.
entryA 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

CodeExitNotes
validation_error2--parent-only and --entries-only are mutually exclusive.
not_found6No run with that id under that workflow, or the run’s details have been archived server-side.
auth_forbidden3The API key lacks the terracotta:cli scope.

​
Examples

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'