clay.com

Command Palette

Search for a command to run...

Inspecting a Workflow's Snapshot History 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}.

Inspecting a Workflow's Snapshot History with the Clay CLI

clay workflows snapshots reads a workflow's automatic version history: an immutable, content-addressed capture taken at creation, after every node edit, and at the start of a run. Every workflow has at least one snapshot from the moment it was created, and the newest snapshot reflects the workflow's state as of that capture, not the state before whatever triggered it.

What you will build

A snapshot listing on a workflow that has existed since creation with no further edits, then a single node edit, to show what the newest snapshot actually contains afterward.

clay workflows snapshots list <workflowId>        (one entry: the creation baseline)
    ↓
clay workflows nodes create <workflowId> --input '{...}'
    ↓
clay workflows snapshots list <workflowId>        (a new, newest entry containing the added node)

AI Prompt

Using the Clay CLI, read a workflow's automatic snapshot history and confirm what each
capture actually contains.

Requirements:
- `clay workflows snapshots list <workflowId>` returns { data: [{ id, hash, createdAt,
  nodeCount, edgeCount }] }.
- A snapshot is captured at creation, after a node edit, and at the start of a run, so a
  workflow with N snapshots has been edited (or run) N-1 times since creation, not N times.
- The newest snapshot after an edit contains that edit's result, not the state before it.
  Restoring to the newest snapshot restores the just-made change, not the change before it.
- A `restore` call changes the ordering: the restored snapshot is not guaranteed to sort as
  the newest entry afterward. Confirm order by `createdAt`, not by list position, when it
  matters.
- 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 snapshots

clay workflows snapshots list wf_example

Real output, for a workflow with no edits since creation:

{
  "data": [
    {
      "id": "wfs_example",
      "hash": "00f62a6696360db4a415b6d24ac05de9cc1a95ad03ce068525f54592d2f697e9",
      "createdAt": "2026-08-14T21:32:27.330Z",
      "nodeCount": 0,
      "edgeCount": 0
    }
  ]
}

Exactly one entry, dated to the workflow's own creation timestamp, confirms this workflow has never been edited.

2. Add a node and list again

clay workflows nodes create wf_example --input '{"nodeType":"delay","name":"Verify","delaySeconds":5}'
clay workflows snapshots list wf_example

Real output, trimmed to the two most recent entries:

{
  "data": [
    { "id": "wfs_new", "createdAt": "2026-09-28T23:55:50.791Z", "nodeCount": 1, "edgeCount": 0 },
    { "id": "wfs_example", "createdAt": "2026-08-14T21:32:27.330Z", "nodeCount": 0, "edgeCount": 0 }
  ]
}

The newest entry has nodeCount: 1, matching the graph immediately after the edit, not the empty graph from before it. Two entries after one edit is also the correct count: the creation baseline plus one new capture, not one capture per edit starting the count at zero.

Verify the result

clay workflows snapshots list <workflowId>

Expected: at least one entry for any workflow, and after any single edit, exactly one additional entry whose nodeCount/edgeCount matches the graph as it stands right after that edit, not before it.

How it works

A snapshot is captured at creation, after a node edit lands, and at the start of a run, so the newest snapshot is always a record of what the workflow currently looks like, not an undo point for the change that produced it. Restoring to that newest snapshot re-applies the same change rather than reversing it; the snapshot to restore to for an actual undo is the one before the unwanted change, not the one right after it. Because a run start also produces a snapshot, and even an edit attempt that fails validation without changing anything can still add one, the list's length tracks capture events broadly, not strictly successful edits, and a workflow with N entries has had N-1 captures since its creation baseline, not N edits.

get fetches one snapshot's full graph rather than only its summary counts. restore rolls the live workflow back to a specific snapshot, but the restored snapshot does not necessarily reappear as the newest entry in a later list call: ordering can follow when a snapshot was originally captured rather than when it was last restored to, so confirm by createdAt rather than by position when the exact order matters.

Common issues

A single snapshot does not mean the workflow is broken or incomplete

It means no edits have happened since creation. Check nodeCount/edgeCount on that same entry, or clay workflows graph get, to judge whether the workflow itself is empty, not the snapshot count.

The newest snapshot is not an undo point for the change that created it

Restoring to the snapshot captured right after an edit reapplies that same edit rather than reverting it. To undo a specific change, restore to the snapshot immediately before it in createdAt order, not the newest one in the list.

Snapshot count mixes edits, run starts, and failed attempts

A higher snapshot count does not mean more successful edits specifically: starting a run and even a rejected edit attempt can each add a capture. Use nodeCount/edgeCount/hash differences between consecutive entries to judge whether a given capture actually represents a graph change, rather than reading the count alone.

Snapshots capture more than published changes

For only the subset of history that was explicitly published, use clay workflows versions instead; snapshots is the complete autosave trail, which is typically much longer and includes captures that were never published.

Next steps

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay workflows nodes create <workflowId> --input '{...}' && clay workflows snapshots list <workflowId>"
  expected_result: "After the edit, the newest snapshot's nodeCount/edgeCount matches the graph as it stands right after the edit, and the list has exactly one more entry than before."

Related Articles