← 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": "Use for advanced Clay people/company searches involving geography, industry, growth, employer history, audiences, relationships, counts or fields beyond the searches starter, and for query validation or quota errors.",
"included_files": [],
"name": "searches-advanced",
"skill_md_contents": "---\nname: searches-advanced\ndescription: Use for advanced Clay people/company searches involving geography, industry, growth, employer history, audiences, relationships, counts or fields beyond the searches starter, and for query validation or quota errors.\nallowed-tools: Read, Grep\n---\n\n# Advanced Clay search\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\nSearch Clay's GTM database with advanced queries and return matching records — people or\ncompanies.\n\n**Audiences** is the workspace's own people and companies — read and segment what they already have.\n**Search** is Clay's GTM database for net-new lists. This is not the tables entry-point skill (querying\ndata already in a table) and not the workflows entry-point skill (automations). Reach for Search when the\nuser wants to _find_ prospects or accounts not in the workspace yet.\n\n## How it works\n\nA search is a three-step, forward-only iterator:\n\n1. **Discover** the query grammar and queryable fields.\n2. **Create** the search and receive a `searchId`.\n3. **Run** it to pull the next page of records. Repeat while `hasMore`\n is `true`.\n\nThere is no cursor: the iterator's position lives server-side and can't be replayed, so\neach `run` call returns the records after the previous one.\n\nBefore authoring a query, fetch only the reference sections the query needs, once per\nconversation. Start with `grammar`, `rules`, and the field catalog for your entity:\n\n```bash\nclay searches query-mode reference --sections grammar,rules,people-fields | jq -r '.reference'\n```\n\n| Section | Fetch when |\n| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `grammar`, `rules` | Before you write the first query in a conversation: syntax, scopes, functions, and query policies. Skip them on later fetches. |\n| `people-fields` | The search returns people. |\n| `company-fields` | The search returns companies, or a people search filters on employer attributes (`company.*` inside `experiences.any(...)`). It is the largest section, so skip it when you don't need it. |\n| `company-people-fields` | A companies search filters on its employees. It lists only what differs from `people-fields`; add `people-fields` too only if you need the shared fields and their allowed values. |\n| `job-fields` | The query filters on hiring. |\n| `examples` | You want worked queries. |\n| `workspace-resources` | The query references audiences or tables. |\n\nEvery field name and allowed enum value is in the field catalogs; a value that is not listed\nfails validation. Request the fewest sections that cover the query and make a second call if\nyou find you need another. Sections come back in a fixed order, and an unknown name fails with `validation_error`.\n\nIf you do need every section, omit `--sections`. It is too large for one tool result, so\nsave it to a file and never print it to stdout:\n\n```bash\nclay searches query-mode reference | jq -r '.reference' > ./clay-search-reference.md\ngrep -n '^##' ./clay-search-reference.md\n```\n\nDo not re-read sections already in your context. If a query fails validation, fix it from the\nerror message and the field catalog, then retry. Queries return people or companies only; job-posting criteria are nested\nfilters on those (`jobs.exists(...)`, `company.jobs.any(...)`). Workspace audience\nreferences are covered in the Audiences section below.\n\nRun `clay searches --help` (and `clay searches <cmd> --help`) for flags and output shapes.\nFor tool access or authentication problems, read the `clay` entry skill before continuing.\n\n## Audiences\n\nThe query language supports `@audience_segment(\"segmentId\")` references; they resolve\nagainst the workspace when the search runs. `clay searches query-mode reference` also\nserves the Clay UI, so wherever it says to route an audience to a picker (\"Resource\nselection required … in the Clay Search panel\"), that applies only to the UI surface.\nWhen authoring a query here, resolve the audience yourself:\n\n- To exclude everything the workspace already has — \"exclude my existing contacts\",\n \"net-new accounts only\", \"not already in Clay\", \"exclude all my audiences\" — use the\n built-in sentinel `@audience_segment(\"ALL\")`, the whole Audiences dataset for the\n query's entity: `clay.exclude_people_identifiers(@audience_segment(\"ALL\"))` or\n `clay.exclude_company_identifiers(@audience_segment(\"ALL\"))`. No lookup, no segment to\n create. Only resolve a specific segment when the user names a particular audience.\n- `clay audiences list --entity-type people|companies` returns segment ids. Contact\n segments match people queries; Account segments match companies queries. Follow each\n response's `cursor` with `--cursor` until it is absent before matching a name or\n checking for duplicates. Write the id into `@audience_segment(\"<segmentId>\")`. The\n reference's \"Workspace resource references\" section (`--sections workspace-resources`) has the function signatures — e.g.\n `clay.exclude_people_identifiers(@audience_segment(\"SEGMENT_ID\"))` to exclude a Contact\n audience, or `clay.filter_to_companies(@audience_segment(\"SEGMENT_ID\"))` to target\n current employers from an Account audience.\n- Never invent a segment id. If the user names an audience you cannot resolve, or\n several segments match, follow \"Choosing a segment\" in the `audiences` skill:\n list segments, then ask with them as choices.\n\n## When a criterion isn't supported\n\nCheck the reference before deciding whether it can express the criteria. Do not invent a\nfield or operator that is not in the reference.\n\nIf the query can't express a criterion, split the request into what search _can_ do and what\na routine does:\n\n1. Search on the closest available built-in criteria to get a candidate set (e.g. industry,\n size, or title criteria that approximate the intent).\n2. Feed those results into a saved routine that enriches or scores each record for the\n attribute the user actually asked about, then filter or act on that routine's output.\n\nTell the user the field isn't a native search filter and offer this search → routine path\nrather than returning nothing. See the `routines` skill and \"Next: enrich or persist the\nresults\" below for the handoff.\n\n## Warn before large generic searches\n\nBefore `create`, if the ask is generic and large — few criteria beyond something like\nindustry + location (e.g. \"all tech companies in NYC\") — stop and suggest refining first.\nOffer 2–3 concrete narrowing options search can express (company size, title/seniority,\nopen roles, tech stack, products and services, named companies/domains, or a small result\n`limit`). Do not create until they confirm or narrow; continue with the broad query only if\nthey insist. Skip when the ask is already clearly bounded. After they insist, still apply\n**Warn before near-exhaustion** below when relevant.\n\n## Start a search\n\n```bash\nclay searches query-mode reference --sections grammar,rules,people-fields | jq -r '.reference'\nclay searches query-mode create --query '<query>'\n```\n\n`create` returns `{ \"searchId\": \"search_...\" }`.\n\n### Paging\n\n`run` returns `{ \"data\": [ ... ], \"hasMore\": <boolean>, \"periodQuota\"?: { \"limit\", \"used\",\n\"remaining\", \"resetsAt\" } }`. `--limit` is the page size. `periodQuota` appears on\nsuccessful `run` responses only — not on `create`; do not invent values.\nReuse the same `searchId`; each call returns the next page. Continue while `hasMore` is\n`true`, but after every `run` that returns `periodQuota`, apply **Warn before\nnear-exhaustion** below before the next page. Stop when `hasMore` is `false`, or when the\nquota is near exhaustion — unless the user explicitly asks to continue.\n\n```bash\nclay searches query-mode run <searchId> [--limit <n>]\n```\n\n## Warn before near-exhaustion\n\nKeep routine quota checks internal under the shared cost policy in `workflows-discover-actions/cost-and-budget.md`. Do not\nannounce a quota or seek approval merely because a search consumes results. The verified\nnear-exhaustion condition below is an exception.\n\nWhen `periodQuota` is present, before a create or run that will consume `N` results (the\nvolume you plan to pull, not the full match set), check `remaining − N`. If that would\nleave under 15% of `limit`, stop and ask first:\n\n> This search will return {{N}} results and leave {{remaining − N}} of your period quota.\n\nContinue only if they confirm. Otherwise offer a smaller pull that keeps at least 15%\nremaining, or stop. Skip when `periodQuota` is absent.\n\nExample: `limit` 10,000, `remaining` 2,000, `N` 1,500 → 500 left (5% of cap) → warn.\n\n## Quotas\n\nIf a create or run fails with `quota_exceeded` (exit 1, HTTP 402), the workspace has hit a\nplan result cap (per-request, per-search, or period) or a credit/usage limit. Short backoff\nwill not help. Read the error message and choose one of:\n\n1. **Per-request size** — message names a \"per request\" limit. This is the only exception:\n reissue once with `--limit` ≤ that cap (e.g. free plans often allow 50 per request).\n2. **Per-search, period, or credits** — anything else. Stop spending allowance: no further\n `run` at any `--limit` (including 1), and no new `create` to work around a per-search\n cap. The report is the finished deliverable. Give the short cap account from the error\n (upgrade, named period reset, or contact support). Always include the plan selector —\n resolve `<workspaceId>` with `clay whoami | jq -r '.workspace.id'` when the error has no\n URL: `https://app.clay.com/workspaces/<workspaceId>/billing/plan-selector` (bare URL;\n prefer a plan-selector URL from the error when present). If the error includes an upgrade\n URL or upgrade copy, make that selector extremely prominent: near the top of the reply\n and again as the last line (`Upgrade your plan now at: <url>`). If the error says to\n contact support, lead with that path and still add one plan-selector line so they can\n self-serve if they prefer. Also share the public search docs for follow-up questions:\n `https://developers.clay.com/searches#result-limits`. If the user asks to upgrade their\n plan, open the plan selector link for them. Pull a remainder only if they ask for it in a\n later message after that report; the original request for N results is not that ask.\n\n`validation_error` (exit 2) means malformed input (bad flags/filters/query), not a quota.\n`server_error` (exit 1) on query-mode create/run can be a transient upstream fault (on `run`,\ne.g. the semantic-query embedding service timed out). On `create`, retry once after a short\nwait. On `run`, retry once only when no data came back — a retry re-serves the current page\nand can charge and count it again if the failure happened after billing.\n`rate_limited` (exit 4) is a short HTTP 429 backoff and may be retried after `details.retryAfter`.\n\n## Next: enrich or persist the results\n\nSearch only _finds_ records. After paging results, offer one of two plugin paths — both via\n`clay routines runs start`. See the `routines` skill for sizing runs and fetching results.\n\n### Enrich without persisting\n\n**Prefer Clay-managed routines for standard enrichment.** Before reaching for the raw\naction catalog or building a workflow, list the full, paginated routines set and check\n`source: managed` first. Clay ships managed routines that cover most enrichment — e.g.\n**Work Email**, **Company Domain**, **Enrich Person**, **Enrich Person and Find Contact\nDetails**, **Company Job Openings**. Match on each routine's input schema\n(`clay routines get <id>`), not its name. Only fall through to the action catalog or a new\nworkflow when no managed or custom routine fits.\n\n```bash\nclay routines list\n```\n\n```bash\nclay routines get function:t_abc123\n```\n\nAfter Search has results, use the **`routines` skill** to start the run: list or get\nthe routine schema, then `clay routines runs start`.\n\n### Persist into Audiences\n\nWhen the user wants Search hits **kept in the workspace**, find or create a routine whose\nunderlying workflow upserts with `upsert-audiences-record`. If none exists, build the workflow\nusing the `workflows` skill's `audiences.md`, then to run in bulk see the `routines` skill.\n"
}SHA-256 of public snapshot: 94dfb119b7d8c648895c8256542e2a097c80d889b3fe2f7306add57d7f5fd981