← ClayCONTENT HISTORY

Update to Clay

Snapshot Nov 18, 2026 · 06:19 UTC · version 2.38.0

Collection source: downloaded plugin package.

WHAT CHANGED

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 JSON
Full technical diff · 0 changed fields
Full snapshot data
{
  "description": "Clay routines — create a routine from an existing function/workflow, then run a saved routine that exists in this workspace. Use when the user asks to create/register a routine, or to run, execute, or trigger a function, workflow, or routine (by name or id), pass it inputs, or check the results/status of a run. For building a new workflow, use the workflows entry-point skill instead.",
  "included_files": [],
  "name": "routines",
  "skill_md_contents": "---\nname: routines\ndescription: Clay routines — create a routine from an existing function/workflow, then run a saved routine that exists in this workspace. Use when the user asks to create/register a routine, or to run, execute, or trigger a function, workflow, or routine (by name or id), pass it inputs, or check the results/status of a run. For building a new workflow, use the workflows entry-point skill instead.\n---\n\n# Running Clay routines\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\nA **routine** is the runnable unit in Clay: a saved **function** or **workflow** that\nalready exists in this workspace. This skill is about _running_ an existing routine and\ngetting its results — not building one.\n\n- To **build or edit** a workflow, use the workflows entry-point skill.\n- If no existing routine matches a request for custom Claygent or LLM work, use the\n  `/workflows-claygent` skill to build and run it.\n- To **query data** out of a Clay table, use the tables entry-point skill.\n- To **find the records** to run a routine over, use the `searches` skill for net-new people\n  or companies, or the `audiences` skill for members of a saved audience, then feed the\n  results in here.\n- To **write people or companies into Audiences**, run a routine whose underlying\n  workflow contains `upsert-audiences-record` (for example, to persist Search results).\n  Items pipe in the same as other runs, using `workflow:<id>` instead of `function:<id>`.\n  If no such workflow exists, build it via the `workflows` skill's\n  `audiences.md`, then `clay routines create workflow`.\n- To run a routine **over HTTP** from a service or app (not a one-off shell task), use\n  the `public-api` skill.\n\nRoutines run **asynchronously**: you start a run, then poll for results.\n\n## 1. Find the routine\n\nDon't assume a routine id. List what exists and match the user's request to one:\n\n```bash\nclay routines list            # routines in this workspace\nclay routines get <id>        # full config and input schema\n```\n\n`clay routines list` is **paginated** — a workspace can have far more routines than one\npage. Page through with `--cursor` until the response has no `cursor` before concluding a\nroutine doesn't exist. Each routine carries a `source` field in the response — `list` has no\nfilter flag, so filter client-side (e.g. `| jq '.data | map(select(.source == \"managed\"))'`).\n`managed` routines are Clay's built-in enrichers\n(emails, domains, firmographics) and should be your first choice for standard enrichment;\n`custom` are workspace-built. Decide by **input schema**, not name — e.g. the managed\n**Work Email** routine needs Full Name + Company Name + Company Domain, so resolve the\ndomain first with the managed **Company Domain** routine when you only have a company name.\n\n`clay routines get <id>` is important before running: it shows the routine's **input\nschema** so you know exactly which fields each item needs.\n\n### Link the user to the underlying function or workflow\n\nWhenever you show the user a routine — from `clay routines list` or `clay routines get` —\ngive them a link to open its underlying object in the Clay app so they can inspect or edit\nit. This matters most in a headless environment (Claude Code, Cursor, a shell) where the\nuser has no Clay tab open.\n\nA routine id encodes the object it wraps: `function:<tableId>` wraps a table,\n`workflow:<workflowId>` wraps a workflow. Split off the id after the `:` and combine it\nwith the workspace id (`clay whoami | jq -r '.workspace.id'`) to build the link:\n\n- **Function** (`function:<tableId>`) → `https://app.clay.com/workspaces/<workspaceId>/tables/<tableId>`\n- **Workflow** (`workflow:<workflowId>`) → `https://app.clay.com/workspaces/<workspaceId>/terracotta/tc-workflows/<workflowId>`\n\nFor **function** routines, both `list` and `get` return a `source` (`managed` for a\nClay-managed default function, `custom` for one built in this workspace) and, for custom\nfunctions, a `createdBy` (`{ id, name, email }`; `null` for managed ones). Use these to tell\nthe user which functions are Clay-managed vs. their team's own, and who authored a custom\none — e.g. group them by `source`, or note the author when disambiguating similar functions.\n\n### Workflow functions\n\nWorkflow functions are functions backed by workflows. Their callable id is\n`workflow:<workflowId>`, not `function:<workflowId>`. Discover them with\n`clay workflows actions search` or `clay functions list` (includes published workflow functions when enabled).\nFunction listing returns workflow functions first, then table functions, newest first within each group.\nFollow pagination cursors to reach table functions; the first page is not the newest functions overall.\nInspect a workflow function with `clay functions get workflow:<workflowId>` before registration.\nThis returns the published input/output schemas and the underlying `id`. The `schema` string\ncontains the published workflow implementation, like the implementation context returned for table functions.\n`candidateId` is a search identifier; do not use it as a routine id.\n\nRegister a workflow function with `clay routines create workflow <workflowId> --name \"My function\"`\nusing the raw `id`, then run it with `clay routines runs start workflow:<workflowId>`.\nWorkflow functions need no `--entity-type`. Registration is required for routine execution,\nbut not for inspection or inserting a `subworkflow_call` into another workflow.\nDirect routine runs use the workflow's normal manual trigger, including its configured snapshot pin.\nTo test unpublished changes, set that trigger's `snapshotId` to `latest` with `clay workflows triggers update`.\nRead `clay routines get workflow:<workflowId>` for the inputs accepted by a direct run.\nA `subworkflow_call` uses the latest published version by default; function inspection describes that published version.\n\n### Create a routine from an existing function or workflow\n\nIf no routine exists yet for a function (a table) or a workflow, expose it as a runnable\nroutine with `create`. This registers the underlying object as a routine.\n\n```bash\nclay routines create function <tableId> --name \"My contact routine\" --entity-type contact\nclay routines create workflow <workflowId> --name \"My workflow routine\"\n```\n\n- `type` is `function` or `workflow`; `objectId` is the table id (function) or workflow id.\n- `--name` is **required** for both types.\n- `--entity-type` (`contact` or `company`) is **required** for function routines and rejected\n  for workflow routines.\n- The routine id is built from the type and object id, e.g. `function:t_abc`.\n\nUse `clay routines update <id>` to change a routine's name, description, or entity-type\nlater. See `clay routines create --help` / `clay routines update --help` for the full flags\nand JSON shape.\n\n## 2. Check the cost and your balance before running\n\nBefore starting a run, inspect its estimate and the workspace balance internally. Follow\nthe shared cost policy in `workflows-discover-actions/cost-and-budget.md` for disclosure and confirmation; ordinary authorized\nruns do not need a cost-only check-in. `clay routines get <id>` includes a per-item estimate;\n`clay credits balance` returns the remaining balance.\n\n```bash\nclay routines get function:t_abc123 | jq '.estimatedCreditCost'\nclay credits balance | jq '{ balance, actionExecutionBalance, user }'\n```\n\nThere are **two independent workspace budgets**, and a run needs enough of each:\n\n- `estimatedCreditCost.perRun` is charged against the data-credit `balance`.\n- `estimatedCreditCost.actionExecution` (when supplied) is charged against the separate\n  `actionExecutionBalance` on action-execution pricing plans. A workspace can have plenty\n  of `balance` but no action executions left — enough of one budget does not cover the other.\n  A missing or null `actionExecution` does not identify the plan: it means the workspace is\n  on legacy billing **or** the estimate carries no priced action executions. Whether\n  `clay credits balance` returns `actionExecutionBalance` is what tells the plans apart —\n  present means action-execution pricing, absent means legacy.\n\nA run billed to the user also counts against their personal monthly credit limit,\nreported as `user.limit` and `user.balance` (both null when they have none). Whether a run\nis billed to the user depends on workspace settings, so treat `user.balance: 0` as a likely\nblocker to mention, not a verified shortfall. A credit budget assigned to the user can also\nstop a run, and `clay credits balance` does not report it.\n\nFor how to read the balance and how the cost fields work, see the help text:\n\n```bash\nclay credits balance --help\n```\n\nOnly multiply per-item costs when they apply to the configured execution and all relevant\nexecution counts are known. Workflow estimates count nodes once and can omit branching\nand fan-out; `containsVariablePricing: false` does not establish completeness. Do not turn\nan incomplete base estimate into a total, even by labeling it approximate.\n\nIf a supported estimated total for **either**\nbudget exceeds its matching balance — `perRun × items > balance`, or\n`actionExecution × items > actionExecutionBalance` — stop and tell the user instead of\nstarting a run that will only partially complete.\n\nUndefined, null, incomplete, or inapplicable costs are unknown, not free. If asked, explain\nthat the total cannot be reliably estimated; otherwise continue within the authorized scope.\n\n### Running low? Share a top-up link\n\nWhen supported pricing shows insufficient balance, or a real billing failure occurs, read the\n`credits-quotas-plans` skill and follow it for CLI top-up, auto top-up, and\nbilling UI options.\n\n## 3. Run it\n\nStart an async run, passing inputs per item:\n\n```bash\nclay routines runs start <id>     # see --help for how to pass items/inputs\n```\n\n- A single inline run takes **1-100 items**; each item is a set of `inputs` matching the\n  routine's input schema.\n- For larger sets, routines support a **batch** run over an uploaded JSONL file.\n- A run can answer `approval_required`, because a routine's steps can act outside Clay. Present\n  the request for approval as the `cli` skill describes. Approving starts the run, so don't run\n  the command again.\n\nRun `clay routines runs start --help` for the exact flags, the input/JSON shape, and how\nto supply items.\n\n## 4. Get the results\n\nRuns are asynchronous. Prefer a single blocking call with `--wait` instead of hand-rolling a\npoll loop:\n\n```bash\nclay routines runs get <run-id> --wait 60        # poll until complete / validation_failed / processing_failed, or 60s\nclay routines runs get <run-id> --bulk --wait 60 # same for a bulk run (skip the inline probe)\nclay routines runs get <run-id> --wait           # poll until complete / validation_failed / processing_failed (no budget)\nclay routines runs get <run-id>                  # single request (may still be in_progress)\nclay routines runs get <run-id> --bulk           # look up as a bulk run (bare flag, no value)\nclay routines runs list                          # recent runs and their statuses\n```\n\nCheck `.status` on the JSON before treating the run as done. With bare `--wait`, the command\nblocks until `complete`, `validation_failed`, or `processing_failed`. With `--wait <seconds>`, if the budget expires\nwhile still `in_progress`, the command exits 0 with that latest status — do not assume success.\nPrefer a bounded `--wait <seconds>` for bulk runs: a bulk run that was stopped keeps reporting\n`in_progress`, so bare `--wait` can wait forever.\n\nEvery response carries a `mode` of `inline` or `bulk`, and so does the output of\n`runs start`. When it is `bulk`, pass `--bulk` on `runs get` so the run is looked up directly.\nIf you don't know the mode — a run id you were handed, or one from `runs list`, which does not\nreport it — omit `--bulk`; the response tells you the mode.\n\nA completed bulk run reports a `resultUrl` rather than inline `data`. That URL is short-lived\n(minutes) — download it promptly, and re-run `runs get --bulk` to mint a fresh one rather\nthan reusing a stale link. Results stay retrievable for about a day after the run finishes,\nafter which the id stops resolving.\n\nPer-item results come back with a status (`complete` / `failed`) and either a `result`\nor an `error`.\n\nWhile an inline run is still `in_progress`, the response can include `data` with the items\nthat have finished so far (up to `--limit`, no `cursor`). Use those to act on early results\nor show progress, but wait for `complete` before treating the result set as final.\n\n`clay routines runs get` returns a single page of inline results. Since an inline run\nhas at most 100 items, `--limit 100` returns every result in one page. If you use a\nsmaller page size, the response includes a top-level `cursor` when more results remain —\npass it back via `--cursor` to fetch the next page.\n\n## Authoritative details\n\n```bash\nclay routines --help\nclay routines <cmd> --help\n```\n"
}

SHA-256 of public snapshot: 3b4ab188e22c71956645af7287b5214bf7f007fb6fa41b310d93059820dd87f7