Skip to main content
List the runs of a workflow, newest first. Filter by status, creation time, snapshot version, or a free-text search over run inputs, outputs, and error. Use clay workflows runs get to inspect a single run. 
clay workflows runs list <workflowId> [--status <status>] [--created-after <datetime>] [--snapshot-id <id>] [--search <text>] [--limit <n>] [--cursor <token>]

​
Arguments

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

​
Flags

FlagDescription
--status <status>Filter by run status. Repeatable to match any of several statuses.
--created-after <datetime>Only runs created at or after this datetime.
--snapshot-id <id>Only runs of this workflow snapshot version.
--search <text>Case-insensitive text search over run inputs, outputs, and error.
--limit <n>Page size, 1–100. Defaults to the server page size (50) when omitted.
--cursor <token>Resume from a previous response’s cursor to fetch the next page.

​
Output

{
  "data": [
    {
      "runId": "wfr_xyz789",
      "workflowId": "wf_abc123",
      "workflowName": "Lead enrichment",
      "status": "completed",
      "createdAt": "2026-06-01T00:00:00Z",
      "updatedAt": "2026-06-01T00:04:10Z",
      "workflowSnapshotId": "wfs_123",
      "batchId": "batch_123",
      "triggerId": "trg_123"
    }
  ],
  "cursor": "next_page_token"
}
FieldTypeDescription
data[].runIdstringRun id. Pass to clay workflows runs get.
data[].workflowIdstringWorkflow the run belongs to.
data[].workflowNamestring | nullWorkflow display name, or null.
data[].statusstringRun status. See the status values below.
data[].createdAtstringWhen the run was created.
data[].updatedAtstringWhen the run was last updated.
data[].workflowSnapshotIdstringSnapshot version the run executed.
data[].batchIdstringPresent when the run is part of a batch.
data[].triggerIdstringPresent when the run was started by a trigger.
cursorstringPresent when more runs are available. Pass it back via --cursor.
Run status is one of: pending (queued but not yet started), running (actively executing nodes), waiting (blocked on an async operation or concurrency slot), paused (paused by an operator — resume to continue), completed (finished successfully), or failed (terminated with an error).

​
Errors

CodeExitNotes
validation_error2--status is not a known status, --created-after is not a valid datetime, or --limit is out of range.
not_found6No workflow with that id.
auth_forbidden3The API key lacks the terracotta:cli scope.

​
Examples

clay workflows runs list wf_abc123 | jq -r '.data[].runId'
clay workflows runs list wf_abc123 --status failed
clay workflows runs list wf_abc123 --status failed --status completed
clay workflows runs list wf_abc123 --created-after 2026-06-01T00:00:00Z --search clay.com
clay workflows runs list wf_abc123 --limit 100 | jq -r '.data[].runId'
clay workflows runs list wf_abc123 --cursor "$CURSOR" | jq -r '.cursor'