# Routines > 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. - Skill: `clay-run/routines` (Agent Skill) - Install (CLI): `npx skillmds@latest add clay-run/routines` - Raw SKILL.md: https://api.skillmd.com/api/skills/clay-run/routines/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: clay-run (https://skillmd.com/u/clay-run) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/clay-run/routines --- # Running Clay routines A **routine** is the runnable unit in Clay: a saved **function** or **workflow** that already exists in this workspace. This skill is about _running_ an existing routine and getting its results — not building one. - To **build or edit** a workflow, use the workflows entry-point skill. - To **query data** out of a Clay table, use the tables entry-point skill. - To **find the records** to run a routine over, use the `searches` skill for net-new people or companies, or the `audiences` skill for members of a saved audience, then feed the results in here. - To **write people or companies into Audiences**, run a routine whose underlying workflow contains `upsert-audiences-record` (for example, to persist Search results). Items pipe in the same as other runs, using `workflow:` instead of `function:`. If no such workflow exists, build it via the `workflows` skill's `audiences.md`, then `clay routines create workflow`. - To run a routine **over HTTP** from a service or app (not a one-off shell task), use the `public-api` skill. Routines run **asynchronously**: you start a run, then poll for results. ## 1. Find the routine Don't assume a routine id. List what exists and match the user's request to one: ```bash clay routines list # routines in this workspace clay routines get # full config and input schema ``` `clay routines list` is **paginated** — a workspace can have far more routines than one page. Page through with `--cursor` until the response has no `cursor` before concluding a routine doesn't exist. Each routine carries a `source` field in the response — `list` has no filter flag, so filter client-side (e.g. `| jq '.data | map(select(.source == "managed"))'`). `managed` routines are Clay's built-in enrichers (emails, domains, firmographics) and should be your first choice for standard enrichment; `custom` are workspace-built. Decide by **input schema**, not name — e.g. the managed **Work Email** routine needs Full Name + Company Name + Company Domain, so resolve the domain first with the managed **Company Domain** routine when you only have a company name. `clay routines get ` is important before running: it shows the routine's **input schema** so you know exactly which fields each item needs. ### Link the user to the underlying function or workflow Whenever you show the user a routine — from `clay routines list` or `clay routines get` — give them a link to open its underlying object in the Clay app so they can inspect or edit it. This matters most in a headless environment (Claude Code, Cursor, a shell) where the user has no Clay tab open. A routine id encodes the object it wraps: `function:` wraps a table, `workflow:` wraps a workflow. Split off the id after the `:` and combine it with the workspace id (`clay whoami | jq -r '.workspace.id'`) to build the link: - **Function** (`function:`) → `https://app.clay.com/workspaces//tables/` - **Workflow** (`workflow:`) → `https://app.clay.com/workspaces//terracotta/tc-workflows/` For **function** routines, both `list` and `get` return a `source` (`managed` for a Clay-managed default function, `custom` for one built in this workspace) and, for custom functions, a `createdBy` (`{ id, name, email }`; `null` for managed ones). Use these to tell the user which functions are Clay-managed vs. their team's own, and who authored a custom one — e.g. group them by `source`, or note the author when disambiguating similar functions. ### Create a routine from an existing function or workflow If no routine exists yet for a function (a table) or a workflow, expose it as a runnable routine with `create`. This registers the underlying object as a routine. ```bash clay routines create function --name "My contact routine" --entity-type contact clay routines create workflow --name "My workflow routine" ``` - `type` is `function` or `workflow`; `objectId` is the table id (function) or workflow id. - `--name` is **required** for both types. - `--entity-type` (`contact` or `company`) is **required** for function routines and rejected for workflow routines. - The routine id is built from the type and object id, e.g. `function:t_abc`. Use `clay routines update ` to change a routine's name, description, or entity-type later. See `clay routines create --help` / `clay routines update --help` for the full flags and JSON shape. ## 2. Check the cost and your balance before running Before starting a run, inspect its estimate and the workspace balance internally. Follow the shared cost policy in `workflows-discover-actions/cost-and-budget.md` for disclosure and confirmation; ordinary authorized runs do not need a cost-only check-in. `clay routines get ` includes a per-item estimate; `clay credits balance` returns the remaining balance. ```bash clay routines get function:t_abc123 | jq '.estimatedCreditCost' clay credits balance | jq '{ balance, actionExecutionBalance }' ``` There are **two independent budgets**, and a run needs enough of each: - `estimatedCreditCost.perRun` is charged against the data-credit `balance`. - `estimatedCreditCost.actionExecution` (when supplied) is charged against the separate `actionExecutionBalance` on action-execution pricing plans. A workspace can have plenty of `balance` but no action executions left — enough of one budget does not cover the other. When not supplied the workspace is still on legacy billing and this balance can be ignored For how to read the balance and how the cost fields work, see the help text: ```bash clay credits balance --help ``` Only multiply per-item costs when they apply to the configured execution and all relevant execution counts are known. Workflow estimates count nodes once and can omit branching and fan-out; `containsVariablePricing: false` does not establish completeness. Do not turn an incomplete base estimate into a total, even by labeling it approximate. If a supported estimated total for **either** budget exceeds its matching balance — `perRun × items > balance`, or `actionExecution × items > actionExecutionBalance` — stop and tell the user instead of starting a run that will only partially complete. Undefined, null, incomplete, or inapplicable costs are unknown, not free. If asked, explain that the total cannot be reliably estimated; otherwise continue within the authorized scope. ### Running low? Share a top-up link When supported pricing shows insufficient balance, or a real billing failure occurs, read the `credits-quotas-plans` skill and follow it for CLI top-up, auto top-up, and billing UI options. ## 3. Run it Start an async run, passing inputs per item: ```bash clay routines runs start # see --help for how to pass items/inputs ``` - A single inline run takes **1-100 items**; each item is a set of `inputs` matching the routine's input schema. - For larger sets, routines support a **batch** run over an uploaded JSONL file. Run `clay routines runs start --help` for the exact flags, the input/JSON shape, and how to supply items. ## 4. Get the results Runs are asynchronous. Prefer a single blocking call with `--wait` instead of hand-rolling a poll loop: ```bash clay routines runs get --wait 60 # poll until complete / validation_failed / processing_failed, or 60s clay routines runs get --bulk --wait 60 # same for a bulk run (skip the inline probe) clay routines runs get --wait # poll until complete / validation_failed / processing_failed (no budget) clay routines runs get # single request (may still be in_progress) clay routines runs get --bulk # look up as a bulk run (bare flag, no value) clay routines runs list # recent runs and their statuses ``` Check `.status` on the JSON before treating the run as done. With bare `--wait`, the command blocks until `complete`, `validation_failed`, or `processing_failed`. With `--wait `, if the budget expires while still `in_progress`, the command exits 0 with that latest status — do not assume success. Prefer a bounded `--wait ` for bulk runs: a bulk run that was stopped keeps reporting `in_progress`, so bare `--wait` can wait forever. Every response carries a `mode` of `inline` or `bulk`, and so does the output of `runs start`. When it is `bulk`, pass `--bulk` on `runs get` so the run is looked up directly. If you don't know the mode — a run id you were handed, or one from `runs list`, which does not report it — omit `--bulk`; the response tells you the mode. A completed bulk run reports a `resultUrl` rather than inline `data`. That URL is short-lived (minutes) — download it promptly, and re-run `runs get --bulk` to mint a fresh one rather than reusing a stale link. Results stay retrievable for about a day after the run finishes, after which the id stops resolving. Per-item results come back with a status (`complete` / `failed`) and either a `result` or an `error`. `clay routines runs get` returns a single page of inline results. Since an inline run has at most 100 items, `--limit 100` returns every result in one page. If you use a smaller page size, the response includes a top-level `cursor` when more results remain — pass it back via `--cursor` to fetch the next page. ## Authoritative details ```bash clay routines --help clay routines --help ```