메뉴
Clay search — find people or companies in Clay's GTM database from structured filters, and page through the matches. Use when the user wants to search Clay for prospects/accounts, not query an existing table.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | search |
| description | Clay search — find people or companies in Clay's GTM database from structured filters, and page through the matches. Use when the user wants to search Clay for prospects/accounts, not query an existing table. |
| allowed-tools | Bash(clay *), Bash(jq *) |
Search Clay's GTM database with structured filters and return matching records — people or companies.
This is different from tables (which queries data already in a Clay table) and from
workflows (multi-step automations). Reach for search when the user wants to find
prospects or accounts.
A search is a three-step, forward-only iterator:
fields.searchId.hasMore
is true.There is no cursor: the iterator's position lives server-side and can't be replayed, so
each run call returns the records after the previous one.
Use the clay CLI. (In Codex/Cursor, run the setup skill once if clay isn't found
or clay whoami fails on auth.) Authenticate with clay login; the workspace is
resolved from the stored session. Output is JSON — pipe it to jq. Run
clay search --help (and clay search <cmd> --help) for the authoritative flags and
output shapes.
clay search filters-mode fields --source-type <people|companies>
clay search filters-mode create --source-type <people|companies> --filters '<json>'
The fields command returns the allowed filter names, types, enum values, and guidance.
Create returns { "searchId": <string> }. --source-type is one of people or
companies.
Search only accepts the filters returned by clay search filters-mode fields for that source type.
When the user wants to narrow by an attribute that isn't in that list — e.g. "companies
using React", "Series A companies", "people who recently changed jobs", "accounts with a
specific tech in their stack", or any derived/enriched signal — do not invent a filter
name or force it into an existing filter. Search cannot evaluate it. Funding amount
ranges are native filters, but funding stages are not.
Instead, split the request into what search can do and what a routine does:
Tell the user the field isn't a native search filter and offer this search → routine path
rather than returning nothing. Read the routines skill (skills/routines/SKILL.md) for how
to find and run one, and see the "Next: enrich or act on the results" section below for the
handoff command.
clay search filters-mode run <searchId> [--limit <n>]
Returns { "data": [ ... ], "hasMore": <boolean> }. --limit is the page size; omit it
to use the server default. Call again while hasMore is true to keep paging.
Run these one at a time, reading the searchId from the create output and passing it
literally to run:
clay search filters-mode fields --source-type people | jq '.fields[].name'
clay search filters-mode create --source-type people --filters '{"job_title_keywords":["growth engineer"],"location_cities_include":["San Francisco"]}'
create prints { "searchId": "srch_..." }. Take that id and page:
clay search filters-mode run srch_abc123 --limit 25 | jq '.data'
Paging is just repeated run calls with the same searchId. Run run, read hasMore
from its output, and if it's true run the exact same command again — the server advances
the iterator for you.
clay search filters-mode create --source-type companies --filters '{"industries":["Software Development"],"country_names":["United States"]}'
clay search filters-mode run srch_abc123 --limit 50 | jq -c '.data[]'
Repeat that run line while the page's hasMore is true; stop when it's false.
Search only finds records. To do something with them — enrich them (emails, firmographics,
social profiles, …) or take an action (send to a CRM, trigger outreach, etc.) — feed the
results into a saved routine. Read the routines skill (skills/routines/SKILL.md)
Search → results → run a routine is the common workflow. Most searches aren't the end goal — the user wants the found records enriched or acted on. After returning results, default to offering this next step rather than stopping at the raw matches.
clay routines list
clay routines get function:tbl_abc123
clay search filters-mode create --source-type people --filters '{"job_title_keywords":["growth engineer"],"location_cities_include":["San Francisco"]}'
Then read the searchId from that output and pull a page straight into a run:
clay search filters-mode run srch_abc123 --limit 25 | jq '{items: [.data[] | {id: .id, inputs: {name: .name}}]}' | clay routines runs start function:tbl_abc123 --input -
Clay — start here. A table of contents for working with Clay and which skill to use for each thing — search (find people/companies), routines (run Clay-managed and custom functions), tables (query/export data), the CLI (ephemeral programmatic access), the Public API (build services on Clay), workflows (build automations, Alpha), and feedback. Read this first to answer "what can I do with Clay?"
Clay Public API — HTTP access for building services, apps, and integrations: structured-filter search over Clay's GTM database, structured table queries, and async routine and batch runs.
Clay setup — authenticate both the `clay` CLI and the Clay MCP server (both are required to use the plugin). Use when `clay` is not found on PATH or the `clay` found in the PATH is the wrong version, `clay whoami` fails, the MCP tools (`read`, `edit_node`) error on auth or don't appear at all despite a Connected server, the CLI isn't signed in, the Cursor plugin never appears after a local install, or the user wants to configure Clay.
Clay tables — analyze what a table does: reconstruct the column DAG, stage it, and narrate the workflow encoded in its columns. Use when the user asks "what does this table do?", "explain the {table} workflow", "walk me through this table", or "what's set up here?".
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?".
Clay workflows — simplify a workflow: merge redundant nodes, cut unnecessary complexity, and replace LLM nodes with deterministic alternatives where possible.