clay.com

Command Palette

Search for a command to run...

Discovering Workflows and Their Graphs with the Clay CLI

Last updated: 9/29/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.

Discovering Workflows and Their Graphs with the Clay CLI

clay workflows list, get, and graph get are the read path for a workflow's identity and structure. graph get in particular is how a genuinely empty workflow (never built out) is told apart from one that simply has no triggers configured yet.

What you will build

A listing of workflows, a fetch of one by id, and its graph summary.

clay workflows list
    ↓
clay workflows get <workflowId>
    ↓
clay workflows graph get <workflowId>

AI Prompt

Using the Clay CLI, discover a workspace's workflows and inspect one's graph structure.

Requirements:
- `clay workflows list` returns { data: [{ id, name, description, type, url, createdAt,
  creator }] }.
- `clay workflows get <workflowId>` returns the same fields for a single workflow, at the
  top level rather than wrapped in a data array.
- `clay workflows graph get <workflowId>` returns { mode: "summary", summary: {
  workflowId, workflowName, workflowUrl, triggers, nodeCount, nodes, edges } }. A workflow
  with nodeCount 0 and an empty triggers array has never been built out, distinct from one
  that has nodes but no configured trigger yet.
- An empty triggers array does not mean the workflow can still be run: `clay workflows
  runs test` rejects a workflow with no trigger configured, regardless of node count.
- 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)
  • At least one workflow in the workspace

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. List workflows

clay workflows list

Real output:

{
  "data": [
    {
      "id": "wf_example",
      "name": "Test Workflow",
      "description": null,
      "type": null,
      "url": "https://app.clay.com/workspaces/<workspace-id>/terracotta/tc-workflows/wf_example",
      "createdAt": "2026-08-14T21:32:27.312Z"
    }
  ]
}

2. Fetch the graph summary

clay workflows graph get wf_example

Real output:

{
  "mode": "summary",
  "summary": {
    "workflowId": "wf_example",
    "workflowName": "Test Workflow",
    "workflowUrl": "https://app.clay.com/workspaces/<workspace-id>/terracotta/tc-workflows/wf_example",
    "triggers": [],
    "nodeCount": 0,
    "nodes": [],
    "edges": []
  }
}

Verify the result

clay workflows graph get <workflowId>

Expected: nodeCount: 0 together with an empty triggers array identifies a workflow that has never been built out, as opposed to nodeCount > 0 with an empty triggers array, which means nodes exist but nothing starts them yet.

How it works

list/get describe a workflow's identity: name, url, who created it. graph get in "summary" mode is the structural view: how many nodes it has, how they connect (edges), and what triggers it (triggers). Reading all three together is how to tell a workflow that was created but left empty apart from one that has real logic in it but is not yet wired to anything that starts it.

Common issues

description and type are frequently null

Neither field is guaranteed to be populated; treat null here as "not set" rather than a sign the workflow failed to load.

An empty triggers array blocks runs test, not only automatic starts

clay workflows runs test <workflowId>

{ "error": { "code": "validation_error", "message": "Workflow has no trigger; add a trigger before running it." } }

A workflow with no configured trigger cannot be exercised with clay workflows runs test at all, regardless of how many nodes it has. A trigger has to exist first (for example a webhook trigger created with clay workflows triggers create) before this command will run.

workflows get is not data-wrapped like workflows list

list returns each workflow inside a data array; get on a single id returns that same set of fields directly at the top level (alongside the usual workspace wrapper), with no data key.

Next steps

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay workflows graph get <workflowId>"
  expected_result: "Returns nodeCount, triggers, nodes, and edges; nodeCount 0 with empty triggers means the workflow has never been built out."

Related Articles