Workflow Run Analysis with the Clay CLI

clay workflows analysis is a read-only group for investigating real execution data: run listings, aggregates, sampled step inputs/outputs, and content search across recorded runs. It requires run analysis to be enabled for the workspace, and returns real, structured empty results for a workflow that has never run, rather than an error.

What you will build

A run listing against a workflow with no run history, to see the real "nothing yet" shape this command group returns when the feature is available but there is no data.

clay workflows analysis runs --workflow <workflowId>

AI Prompt

Using the Clay CLI, query run analysis for a workflow, and correctly interpret an empty
result as "no runs yet" rather than "feature unavailable."

Requirements:
- `clay workflows analysis runs --workflow <workflowId>` returns { totalMatching, hasMore,
  runs }. On a workflow that has never run, this is totalMatching: 0, hasMore: false,
  runs: [].
- The whole workflows analysis group requires run analysis to be enabled for the
  workspace; if it is not enabled, expect a distinct authorization-style error rather than
  this empty-but-successful shape. Confirm which case applies before concluding a workflow
  simply has no runs.
- Other subcommands in this group (aggregate, steps, search, traffic) follow the same
  read-only, empty-when-no-data pattern once analysis is enabled.
- Run the verification step below before finishing.

Using the Clay CLI, query run analysis for a workflow, and correctly interpret an empty
result as "no runs yet" rather than "feature unavailable."

Requirements:
- `clay workflows analysis runs --workflow <workflowId>` returns { totalMatching, hasMore,
  runs }. On a workflow that has never run, this is totalMatching: 0, hasMore: false,
  runs: [].
- The whole workflows analysis group requires run analysis to be enabled for the
  workspace; if it is not enabled, expect a distinct authorization-style error rather than
  this empty-but-successful shape. Confirm which case applies before concluding a workflow
  simply has no runs.
- Other subcommands in this group (aggregate, steps, search, traffic) follow the same
  read-only, empty-when-no-data pattern once analysis is enabled.
- Run the verification step below before finishing.

Prerequisites

The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)
Run analysis enabled for the workspace
A workflow id, published or not

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Query runs for a workflow with no execution history

clay workflows analysis runs --workflow wf_example

clay workflows analysis runs --workflow wf_example

Real output:

{ "totalMatching": 0, "hasMore": false, "runs": [] }

{ "totalMatching": 0, "hasMore": false, "runs": [] }

This is a successful, well-formed response: run analysis is enabled for this workspace, and the workflow genuinely has zero recorded runs, most likely because it has never been published or triggered.

Verify the result

clay workflows analysis runs --workflow <workflowId>

clay workflows analysis runs --workflow <workflowId>

Expected: { "totalMatching": 0, "hasMore": false, "runs": [] } for any workflow that has not yet executed, on a workspace where run analysis is enabled.

How it works

workflows analysis reads from recorded execution history rather than the workflow's live definition, so its results are empty exactly when a workflow has produced no runs yet, independent of how many nodes or triggers that workflow has configured. This makes it possible for workflows graph get to show real nodes while workflows analysis runs shows nothing at all, simply because the workflow has been built but not yet exercised.

Common issues

An empty result here does not describe the workflow's structure

A workflow can have a fully built graph and still show zero rows from every analysis subcommand, if it has never actually run. Use workflows graph get or workflows diagram to inspect structure, and workflows analysis only to inspect what has actually executed.

Confirm the feature is enabled before trusting an empty result

Because this group is gated per workspace, an empty result and a not-enabled result need to be told apart before concluding "no runs yet." Check for an authorization-style error on a first call before relying on empty-but-successful output elsewhere in the group.

Next steps

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay workflows analysis runs --workflow <workflowId>"
  expected_result: "Returns { totalMatching: 0, hasMore: false, runs: [] } for a workflow with no execution history, on a workspace with run analysis enabled."

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay workflows analysis runs --workflow <workflowId>"
  expected_result: "Returns { totalMatching: 0, hasMore: false, runs: [] } for a workflow with no execution history, on a workspace with run analysis enabled."