progress, and only the map/reduce nodes worth watching while a run is in flight. Flags widen the disclosure to every node and to full step payloads. Use clay workflows runs steps for the flat list of individual execution steps.
Arguments
| Argument | Description |
|---|---|
workflowId | Workflow id, e.g. wf_abc123. Required. |
runId | Run id, e.g. wfr_xyz789. Required. |
Flags
| Flag | Description |
|---|---|
--nodes | Include every workflow node in nodes, not just map/reduce nodes. |
--verbose | Implies --nodes. Adds per-node inputs, outputs, parameter mappings, and map/reduce entry steps. |
--node-id <id> | Only include the node with this workflow node id, with full map/reduce results. |
Output
duration is a human-readable string like "2h 3m", "4m 10s", or "12s". error is present only when status is "failed".
Top-level fields
| Field | Type | Description |
|---|---|---|
runId | string | Run id. |
workflowId | string | Workflow the run belongs to. |
workflowName | string | null | Workflow display name, or null. |
status | enum | pending, running, paused, waiting, completed, or failed. |
startedAt | string | When the run started. |
duration | string | Human-readable elapsed time. |
error | string | Present only when status is failed. |
dataCreditsUsed | number | Data credits consumed by the run. |
actionCreditsUsed | number | Action credits consumed by the run. |
progress | object | Aggregate node counts: completed, active, waiting, failed, pending, paused, total, percentage. |
totalEntrySteps | number | Total map/reduce entry steps across the run. |
nodes | array | Per-node summary. Contents depend on the disclosure level (see below). |
Disclosure levels
Each level is a superset of the one above it.| Level | nodes contents |
|---|---|
| (default) | Only map/reduce nodes — the long-running ones worth watching. Regular nodes are counted in progress but omitted from nodes. |
--nodes | Every workflow node, without step payloads. |
--verbose | Implies --nodes. Adds per-node inputs/outputs (full, untruncated payloads — can be very large), nodeType, nextNodes, mappedParameters, parameterSources, and entrySteps on map/reduce nodes. |
--node-id | Just the matching node, with its full map/reduce results inlined. Combine with --verbose to add that node’s payloads too. |
Node object
Each entry innodes carries stepId, nodeId, nodeName, status, startedAt, completedAt, duration, and optional errors. waitingReason appears only when the node is waiting. mapReduce and entryProgress appear only on map/reduce nodes.
mapReduce reports fan-out statistics: dataListId (always present) plus optional totalEntries, totalCount, successCount, failedCount, totalKeys, keyCount, batchSize, tokensUsed, creditsUsed, resultCount, sourceDataListId, errorDetails, and the flags autoGathered, emptyInput, and emptyReduce. The results array is inlined only with --node-id. entryProgress reports total, completed, failed, active, waiting, pending, and percentage.
With --verbose, map/reduce nodes also include entrySteps, an array of { stepId, status, nodeName, entryMetadata?, output?, errors? } where output is truncated to 200 characters.
waitingReason values
map_reduce_processing, waiting_in_queue, agent_tool_execution, tool_execution_pending, claygent_execution_pending, code_execution_pending, wait_timer, workflow_paused, agent_step_limit_reached, unknown.
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 | workflowId and runId arguments are required. |
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. |