← ClayCONTENT HISTORY
WHAT CHANGED
Update to Clay
Snapshot Nov 18, 2026 · 06:19 UTC · version 2.38.0
Collection source: downloaded plugin package.
First saved snapshot
No earlier snapshot is available to establish a change.
Save Clay and check future changes in Following.
Up to 3 plugins free · no card required.
Compare saved observations
Download comparison JSONFull technical diff · 0 changed fields
Full snapshot data
{
"description": "Clay tables — locate a record by identifier and snapshot its state: which table(s) hold it and each cell's status. Use when the user has an id and asks \"trace {id}\", \"where is {id}?\", \"what enrichments ran for this lead?\", or \"is this record done?\".",
"included_files": [],
"name": "tables-trace",
"skill_md_contents": "---\nname: tables-trace\ndescription: 'Clay tables — locate a record by identifier and snapshot its state: which table(s) hold it and each cell''s status. Use when the user has an id and asks \"trace {id}\", \"where is {id}?\", \"what enrichments ran for this lead?\", or \"is this record done?\".'\nallowed-tools: Read\n---\n\n# Trace a record\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\n**Use when:** you have an identifier and want to find the record and see its overall state — \"trace 12345\", \"where is jane@acme.com?\", \"what enrichments ran for this lead?\", \"is this record done?\". This is a **locate + snapshot**: which table(s) hold it, and each cell's status. It does **not** explain _why_ a cell holds what it holds — that's `/tables-value-trace`.\n\nTreat each in-scope table independently. Tables may not share identifiers or have any relationship; presence (or absence) in one says nothing about another.\n\n## 1. Settle scope\n\nResolve which table(s) to look in as in the tables entry-point skill (\"Finding a table\"), or pass a `t_...` id directly. `{id}` is whatever the user gave (email, HubSpot ID, row id, etc.).\n\nIf `{id}` is already a `r_...` row id and the table is known, skip discovery and go straight to **get the row** (step 4).\n\n## 2. Per table: find the identifier's column and archive linkage\n\nFor each in-scope table:\n\n- **`clay tables columns list <tableId>`** — find the column that holds this kind of identifier by matching names (`Email` for an email, `HSID`/`HubSpot ID` for a HubSpot id, etc.). Cache the `f_id → name` map and note column types. The match column must be `basic` to value-filter on it. If several columns could match, or none does, show the columns and ask which to search.\n- **`clay tables get <tableId>`** — read `archive`. If `archive` is non-null, resolve `archive.searchableFieldFormula` (a `{{f_xxx}}`) to its column via the columns list. Plan to search the archive **only if** `{id}` is the value of that indexed column; otherwise the archive isn't searchable by this identifier.\n\n## 3. Search for the record\n\n**If the active table is `queryEnabled`, locate the record with `tables query`** — its server-side filter is more forgiving (`contains`, case-insensitive matching) and scales, so it's the primary tool when query is on. The result carries each matching row's full cell content — value, `fields`, `status`, and any `error` message — so it doubles as the state snapshot; no follow-up call needed:\n\n```bash\necho '{\"tables\":[{\"id\":\"t_abc123\"}],\"filter\":{\"field\":\"f_abc123\",\"op\":\"contains\",\"value\":\"jane@acme.com\"}}' | clay tables query --query - | jq .\n```\n\n**Otherwise, use `clay tables rows list`** with a value filter on the identifier column (shape in the command's `--help`):\n\n```bash\nclay tables rows list <tableId> --filter f_abc123=\"jane@acme.com\" | jq .\n```\n\n`rows list --filter` is exact match, **case-sensitive**. If it comes back empty (`{ \"data\": [] }`), retry **once** with a single predictable variant (lowercase for emails/domains, trim whitespace, or the casing a row sample shows), then stop guessing — say it wasn't found in this table and ask the user to confirm exact spelling/casing.\n\nAlways locate by identifier, never by position: the order `rows list` returns rows in is not the order they appear in the Clay app, so \"the 3rd row\" in the output tells you nothing about what the user sees on screen.\n\nWhere the archive applies (step 2), search it with `rows list` — archives are never query-enabled, so `tables query` is not an option; they're searchable only on the fixed `f_archive_index` column. Filter it by its indexed value (single filter; single capped page, no cursor; values over 255 characters are rejected — pass the first 255):\n\n```bash\nclay tables rows list <archiveTableId> --filter f_archive_index=\"jane@acme.com\" | jq .\n```\n\nRespect the rate limits — batch in small groups, back off on exit 4.\n\nCapture each cell's `status` (and value or error) for the snapshot. A `tables query` result already includes `fields` and full `error` messages. On the `rows list` path, action cells show `fields: null` and abbreviated error labels — get the full detail in step 4. (`rows list` / `rows get` also carry the row's `id` and `updatedAt`, which `tables query` does not.)\n\n## 4. Pull full state where it matters\n\nIf you located via `tables query`, you already have the full snapshot from step 3 — skip this. On the `rows list` path, follow up with **`clay tables rows get`** when:\n\n- any cell is `error` — you need the full `error` message (list only carries an abbreviated label), or\n- the user asked for actual values / enrichment output — `fields` (structured action output) is only populated on `rows get`.\n\n```bash\nclay tables rows get <tableId> <rowId> | jq '.cells | to_entries | map({col: .key, status: .value.status, value: .value.value, err: .value.error})'\n```\n\nMap `col` ids to names from step 2. (`err` is the message string, present only on `error` cells.)\n\n## 5. Report — per table, independent findings\n\nLead with where it is and its overall state; list action/derived columns with status (and value or error where useful). Label each table **active** vs **archive**. Group statuses so the snapshot reads at a glance.\n\nThe `r_` row id is an internal handle, not a report field — you found the record by its business identifier, so lead with that; only show a `r_` id when you already have one (the `rows list` / `rows get` path). `updatedAt` isn't in `tables query` output either, so fetch it with a single `rows list --filter` on the identifier **only when freshness matters** — the active-vs-archive comparison below, or the user asking how recent the data is. Otherwise omit it.\n\n```\nLead Enrichment — archive (updated 2026-04-10):\n Find Email success → \"jane@acme.com\"\n Enrich Person success → {name, title, company}\n Push HubSpot success\n\nAccount Match — active (updated 2026-04-12):\n Match Account queued\n Map Fields empty\n```\n\n- **Found in both active and archive** → likely re-processed; compare `updatedAt` and say which is newer.\n- **Not found** in an in-scope table → say so plainly; it may live in a table you didn't search, or the identifier may be off. Don't treat absence as proof of anything about another table.\n- **An `error` or surprising/empty value** the user wants explained → that's where this skill ends and `/tables-value-trace` begins.\n\n## Hand-offs\n\n- Explain _why_ a specific cell errored, is empty, didn't run, or holds the value it does → `/tables-value-trace`.\n- Table-wide failures rather than one record → `/tables-error-sweep`.\n- \"It's not here and nothing's being added\" → `/tables-capacity`.\n"
}SHA-256 of public snapshot: 358986165dabb9befc1fd317ede18e8363e286b324ded38e5c507328f7d1a4cb