← 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 Audiences — the workspace's own people, companies, and deals (contacts, leads, accounts, customers). Use for any request about their records when no surface is named, including counts, fill rates, lookups (\"how many people have a phone?\"), saved segments, and field definitions. Also deal and pipeline questions like largest opportunities, biggest pipeline items, recent wins, closed-won, deal stage, and ACV. Also Data hub enrichment configuration, audience assignments, and parity checks. Also the calls and meetings synced onto those records, such as Gong recordings, and which accounts discussed a topic on their calls.",
  "included_files": [
    {
      "relative_path": "answering-data-questions.md",
      "size_in_bytes": 10036
    },
    {
      "relative_path": "custom_objects.md",
      "size_in_bytes": 17749
    },
    {
      "relative_path": "filters.md",
      "size_in_bytes": 17569
    },
    {
      "relative_path": "frontend-ast-filters.md",
      "size_in_bytes": 11932
    },
    {
      "relative_path": "queries.md",
      "size_in_bytes": 22755
    }
  ],
  "name": "audiences",
  "skill_md_contents": "---\nname: audiences\ndescription: Clay Audiences — the workspace's own people, companies, and deals (contacts, leads, accounts, customers). Use for any request about their records when no surface is named, including counts, fill rates, lookups (\"how many people have a phone?\"), saved segments, and field definitions. Also deal and pipeline questions like largest opportunities, biggest pipeline items, recent wins, closed-won, deal stage, and ACV. Also Data hub enrichment configuration, audience assignments, and parity checks. Also the calls and meetings synced onto those records, such as Gong recordings, and which accounts discussed a topic on their calls.\n---\n\n# Clay Audiences\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\nAudiences is Clay's CRM-shaped store of **people** and **companies** (plus deal\nrecords). An **audience** — also called a saved segment — is a named filter over\none entity type. Nothing is copied into it: it selects records live, so its\nmembership changes as records change.\n\n**Audiences is the default home for the workspace's own people and companies.**\nWhen a user mentions people, companies, contacts, leads, accounts, customers,\ndeals, or opportunities without naming a surface, they mean these records —\nstart here, not in the tables entry-point skill (a separate surface, right only\nwhen the user names a table) and not in `search` (net-new prospects that are not\nin the workspace yet).\n\nRead this before any audiences work. Supporting references:\n\n- `answering-data-questions.md` — **read this first for any request to count,\n  find, or filter existing records.** Before filtering a categorical field, call\n  `fields list-values` as described there. Also covers field coverage and when\n  to enrich.\n- `queries.md` — **read before searching or counting records. Prefer `--query`,\n  including activity and signal criteria, even when the task will later save an audience.** Audiences DSL grammar,\n  relationship semantics, data or date filters, and server-side sorting for\n  top-N questions.\n- `filters.md` — writing the filter AST to create/update a saved audience, or\n  validate that saved filter. Use it for record searches only when DSL cannot express the criteria.\n- `frontend-ast-filters.md` — supported AST segment-editor fields, operators, and collection\n  shapes. Consult when choosing a saved filter; backend search support is broader.\n- `custom_objects.md` — **deals / opportunities.** Read it before anything that\n  touches them, including vague rankings such as \"largest opportunities\",\n  \"biggest things in our pipeline\", or \"recent wins\", and GTM phrasings:\n  closed-won, closed-lost, open pipeline, deal stage, deal size / ACV / ARR,\n  close date, forecast, win rate,\n  renewal, expansion, churn, \"our customers\". Deals are read-only. Use the DSL\n  `opportunities` root for deal counts and IDs; use people/company roots when\n  the requested results are contacts/accounts associated with those deals.\n- The `workflows` skill’s [enrichments.md](../workflows/enrichments.md) — **read for Data hub enrichment inspection, parity checks, and reuse across\n  segments.** Maps native assignments, provider order, mappings, overwrite rules, schedules,\n  and budgets to the workflow CLI; separates inspection from edits and execution.\n- The `workflows` skill's `audiences.md` — writing values onto records (the\n  `upsert-audiences-record` action) and triggering a workflow off an audience.\n\n**Read with the CLI, write records with the action.** `clay audiences` covers\nevery Audiences primitive — segments, fields, and reading records — but it has no\ncommand that writes a field value onto a record. That is the\n`upsert-audiences-record` action's job.\n\n**Net-new people or companies** — not in the workspace yet. When `search` and `routines`\nare available CLI commands, start in the `searches` skill, then persist via a routine\nwrapping an upsert workflow (the `workflows` skill's `audiences.md`, then the\n`routines` skill).\n\n**Act on this audience** — pull matching records (`records search-ids` / `get`). When\n`routines` is an available CLI command, run a routine over them (see the `routines`\nskill). Ongoing automation (fire when membership\nchanges) is the `workflows` skill's `audiences.md` (`audience_segment` trigger).\n\n## One entity type, three spellings\n\nThe same entity types are named differently depending on where you are. Get this\nmapping right up front — it is the most common source of wasted round trips.\n\n| CLI `--entity-type` | Filter AST / action `entityType` | Filter `dataPath` root        |\n| ------------------- | -------------------------------- | ----------------------------- |\n| `people`            | `CONTACT`                        | `contact_entity_field_values` |\n| `companies`         | `ACCOUNT`                        | `account_entity_field_values` |\n| `deals`             | `CUSTOM` (Opportunity)           | `opportunity`                 |\n\nSupported `--entity-type` values by command (all under `clay audiences`):\n\n| Commands                                                                                         | Accepted values                | Deals support                                              |\n| ------------------------------------------------------------------------------------------------ | ------------------------------ | ---------------------------------------------------------- |\n| `records get`, `records search-ids`, `records search-count`, `fields list`, `fields list-values` | `people`, `companies`, `deals` | Supported; deal searches with this flag must be unfiltered |\n| `list`, `create`                                                                                 | `people`, `companies`          | Not supported; saved audiences target people or companies  |\n| `fields create`, `fields update`, `fields delete`, `fields segments`                             | `people`, `companies`          | Not supported                                              |\n| `signals list --entity-id`                                                                       | `people`, `companies`          | Not supported                                              |\n\nUse these exact plural values: `person`, `company`, and `deal` are invalid.\nCommands not listed above do not take `--entity-type`; segment-scoped commands\nuse the saved audience's type. CLI output can also carry `entityType: \"deals\"`.\nFor filtered deal searches, omit `--entity-type` and use `--query` with the DSL\n`opportunities` root; read `custom_objects.md` first.\n\nWorkflow **triggers** use the middle spelling: an `audience_segment` trigger's\n`segmentId` is the audience id from `clay audiences list`, and its `entityType`\nis `CONTACT` / `ACCOUNT`, not `people` / `companies`.\n\n## Audiences (saved segments)\n\nPrefer dynamic segments: saved audience filters whose membership updates as\nrecords start or stop matching the criteria. Use the user’s request and\nconversation context to determine the filter. Use a fixed cohort with hard coded\nmatching values only when explicitly requested. Read `filters.md` before building\nthe filter, including saved-segment compatibility restrictions.\n\n```bash\nclay audiences list --entity-type people          # id, name, description, entityType (no filter); 50/page, pass back .cursor\nclay audiences get <audienceId>                   # same, plus the full filter AST\nclay audiences create --entity-type people --name \"Missing emails\" --filter ./filter.json\nclay audiences update <audienceId> --name \"…\" --description \"…\" --filter ./filter.json\nclay audiences archive <audienceId>               # soft delete, idempotent; records untouched\n```\n\n- `create` and `update` take `--filter` as inline JSON, **a file path, or `-` for\n  stdin**. Use a file or stdin for anything non-trivial — inline JSON in a shell\n  triggers an approval prompt and invites quoting mistakes.\n- `update` replaces the whole filter; there is no partial merge, and entity type\n  is immutable after creation. Omitted flags are left alone.\n- `get` returns an id-free filter. Inspect it for unsupported clauses\n  before using it to clone an audience; see `filters.md`.\n- `archive` and `fields delete` may answer `approval_required`. Present the\n  request for the user's decision rather than retrying; approving runs it.\n\n### Choosing a segment\n\nWhen the work needs a saved segment and none is identified — no open `audience`\nsurface, an entity-wide view, or a name that matches zero or several segments —\nlook before you ask:\n\n1. Use `clay audiences list --entity-type <type>` to get all segments.\n2. If exactly one segment plausibly fits the request, use it and say which.\n3. Otherwise ask once with your ask-user tool (`AskUserQuestion`; `askUser`\n   inside the Clay app): the 2–3 segments that best fit the request as\n   `choices` — `value` = segment id, `label` = segment name, `description` = its\n   description (or what it contains when it has none) — best match first. When\n   the user is on an entity-wide view, also offer \"All <entity> in this view\".\n   Add `{ type: \"text\" }` so they can name another segment.\n\nNever ask for a segment name with only a text box. If none of the segments fit\nthe request, say so and ask whether they want to create a new segment. If no\nsegments of that type exist, don't offer one; offer the entity-wide scope or\ncreating a segment instead.\n\n## Fields\n\nField ids are what record payloads and filter ASTs key on, and they are scoped\nto an entity type — every subcommand takes `--entity-type`.\n\n```bash\nclay audiences fields list --entity-type people                       # every field: id, name, dataType, fieldType, hidden\nclay audiences fields list --entity-type people --filter id=email     # narrow by id (repeatable, comma-separated)\nclay audiences fields list --entity-type people --include-system      # system fields, hidden by default\nclay audiences fields create --entity-type people --name \"Lead score\" --data-type number\nclay audiences fields update <fieldId> --entity-type people --hidden true\nclay audiences fields delete <fieldId> --entity-type people\nclay audiences fields segments <fieldId> --entity-type people         # audiences whose filter references the field\nclay audiences fields list --entity-type deals                        # deal field definitions\nclay audiences fields list-values title --entity-type people          # distinct values and counts\n```\n\n- **Run `fields list` once and save it** (`> /tmp/people-fields.json`), then slice\n  it with `jq`. Re-running it to grep, head, and parse the same output three\n  different ways is pure latency.\n- `fields list` returns the workspace record-field catalog (system fields\n  excluded) — use those ids for `upsert-audiences-record`.\n- **Names are not ids.** Account \"company name\" is `org_name`. Never guess an id\n  from a display name.\n- **Discover categorical values before filtering.** Use `fields list-values`\n  instead of guessing labels. See `answering-data-questions.md`\n  for value discovery and high-cardinality guidance.\n- `create` silently uniquifies a taken name (`\"Tier (2)\"`) — read the returned\n  `name` and `id` rather than assuming the one you passed.\n- Before `update --data-type` or `delete`, run `fields segments <fieldId>`: a\n  delete rewrites saved filters with those clauses **removed**, changing what\n  those audiences match. Empty `data` means nothing is affected.\n- Default and system fields reject `--name` and `--data-type` changes and cannot\n  be deleted; `--hidden`, `--order`, and `--description` still work.\n\n### Default field ids\n\nPresent in every workspace, so you can write a filter against these without\nlisting fields first:\n\n- **people** — `name`, `first_name`, `last_name`, `email`, `linkedin_url`,\n  `phone`, `title`\n- **companies** — `org_name`, `domain`, `headquarters_location`, `linkedin_url`,\n  `sfdc_owner_id`, `technographics`\n- **deals** — see `custom_objects.md`\n\nAnything else is workspace-defined — get its id from `fields list`.\n\n## Records\n\n```bash\nclay audiences records search-count --entity-type people --audience-id <id>   # count a scope server-side\nclay audiences records search-ids   --entity-type people --audience-id <id>   # matching ids, --limit per page + .cursor\nclay audiences records get --entity-type people --ids 1,2,3                   # field values, max 100 ids\n```\n\nScope for both search commands (`--query`, `--audience-id`, and `--filter` are\nmutually exclusive):\n\n- no scope flag → every record of the entity type\n- `--query <dsl>` → preferred for ad-hoc searches; omit `--entity-type`\n  (combining them is an error). Use `count from ...` for `search-count` and\n  `select from ...` for `search-ids`. Read `queries.md` before constructing the query\n- `--audience-id <id>` → a saved audience's records\n- `--filter <json|file|->` → AST fallback for unsupported DSL constructs;\n  backend query support does not guarantee the frontend can render the filter.\n\nAdd `--archived` to either to search archived records instead of live ones.\n\n**Use `search-count` for \"how many\".** It counts server-side without fetching\nevery ID. A field's `is_not_null` query (or `NotEmpty` AST filter) checks coverage\nwhen relying on unfamiliar data or proposing an enrichment. See\n`answering-data-questions.md`.\n\n**Use `search-ids --query 'select from ... order by <field> desc' --limit N`\nfor top-N people, companies, or deals.** This is the preferred way to answer\n\"Top N\" questions: rank server-side and fetch only the N returned IDs for details,\nwithout paginating through the full record set or sorting it locally.\nBefore ranking, check the field's `dataType` with `fields list`: numeric questions\nrequire a number or currency field, not numeric-looking text. If the type is\nwrong, recommend fixing the Audiences field type before ranking; do not change\nit without approval. Sorting supports one same-entity text, number (including\ncurrency), or date field. Missing values come last. Sorted results have no cursor,\neven if more records match; they are not a full export. To count the same scope,\nuse `count from ... where ...` without `order by` or `limit`. Read `queries.md`\nfor grammar, field discovery, limits, and examples.\n\nFor filtered deal counts and IDs, use `--query` with the `opportunities` root.\n`--entity-type deals` without a query still covers the whole population; combining\nit with `--audience-id` or a non-empty `--filter` is a validation error.\nThe `activities` root supports counts; activity IDs are strings and cannot use\n`search-ids`' numeric pagination. See `queries.md` and `custom_objects.md`.\n\n`search-ids` returns ids only — feed them to `records get --ids` in batches of\n100 for field values, keyed by field id (unset fields may be omitted). Combine\nknown IDs into batches and reuse hydrated records across overlapping scopes. Records\nnot found are omitted rather than erroring. To size a scope, use `search-count`,\nnot a paging loop over `search-ids`.\n\n### Search companies by what was said on calls\n\n```bash\nclay audiences records search-calls --query 'raised pricing objections' --limit 10\n```\n\nUse this when the question is about what was discussed on Gong calls: \"which accounts\nraised pricing objections?\", \"who asked about SOC 2?\". It searches call summaries and\ntranscripts by meaning, so describe what was said rather than listing keywords. It\nreturns company records in the `records get` shape, ranked by best-matching call, with\n`totalMatched` across pages. It returns companies only, not the calls, so answer with the\naccounts and do not quote what was said.\n\nNarrow with `--audience-id`, or intersect the returned `recordId`s with a `search-ids`\nquery for structured conditions. A workspace whose Gong calls are not indexed gets\n`auth_forbidden`; tell the user call transcript search is not enabled there rather than\nfalling back to reading call titles as if they were transcripts.\n\n### Budget the walk before you start it\n\n`search-count` first, then decide whether a full walk is needed. Searches and\nrecord fetches share the workspace's Audiences budget:\n\n- **ids** — unsorted `search-ids` pages at `--limit` ids per call (default 50, max 10,000).\n  Size it from the count: aim for about 10 calls.\n- **field values** — `records get` takes up to 100 ids per call. Batch known ids\n  to reduce requests and fetch only the records needed to answer the question.\n\nWhen that does not fit your data size, **narrow the scope instead of grinding through it**:\ntighten the filter — a shorter date window is usually the biggest\nwin, then a single stage, owner, or segment — or read one page and label the answer\na sample of that scope. Never start an unbounded paging loop and hope it lands: it\nspends the workspace's budget and the user gets a stalled turn instead of an answer.\n\n## Segment activities\n\nUse `clay audiences activities` when the user asks what happened inside a saved\nsegment, such as recent email or call activity, campaign touches, source mix, or\nactivity volume over a period.\n\n```bash\nclay audiences activities list --segment-id audseg_abc --since 2026-08-01 --until 2026-08-20 --activity-types call\nclay audiences activities summary --segment-id audseg_abc --since 2026-08-01 --until 2026-08-20 --activity-types call --sources CLAY_SEQUENCER\n```\n\n- Use `activities list` for the raw activity feed. It returns cursor-paginated\n  events for records in the segment.\n- Event `data` contains source-specific fields when available. The 1 MiB page cap\n  may return fewer events than requested. Follow each cursor until none remains\n  to retrieve all events. An event with `truncated: true` contains partial data;\n  lowering `--limit` does not recover its omitted content.\n- For distinct-record coverage, read `queries.md` and use `--query` with\n  `activities.exists(...)`. Before saving criteria as an audience, follow\n  [Saved segment restrictions](filters.md#saved-segment-restrictions); activity\n  search predicates are not automatically supported saved filters. `eventId` is\n  opaque and must not be parsed for record ids.\n- Use `activities summary` for grouped counts by activity type and source when\n  the user asks for totals, trends, or a quick breakdown instead of individual\n  events.\n- Bound activity reads to the requested time window and activity types. These\n  queries can take a few seconds on large segments, so prefer one targeted\n  request over repeated exploratory calls.\n- It is okay to page through `activities list` with each returned cursor when the\n  user needs the full bounded result set. Continuation requests pass only\n  `--cursor` and optional `--limit`; do not repeat time, activity-type, or source\n  filters with a cursor. Do not loop for freshness or repeatedly rerun broad\n  activity queries without narrowing the request.\n- Common prompts: \"show recent calls for this segment\", \"summarize email activity\n  since last week\", \"which sources drove activity for this audience?\", \"sample the\n  latest campaign activity before I run a workflow\".\n\n### Call search\n\n- For cross-call questions, use `activities search --activity-types call --query`.\n  It searches Gong call summaries and transcript passages, ranked by relevance.\n  To restrict search by record, segment, or date, first use `activities list` with\n  those filters and `--activity-types call --sources GONG`. Follow pagination, then\n  pass the returned eventIds unchanged to `--activity-ids` (up to 1,000). Omitting\n  this flag searches across the workspace. If no calls match the list filters,\n  stop rather than searching without IDs. Returned `recordIds` are company IDs.\n  If `truncated` is true, lower-ranked calls exceeded the 1 MiB response cap;\n  narrow the query or activity IDs to explore further.\n  Matches have no speaker names. Fetch a call's details when attribution or more\n  context matters. Email is not searchable; read it with `activities list`.\n\n## Signals\n\nSignals write activities onto records.\n\nA **signal** on an audience — a watch for job changes, new hires, funding news,\njob postings — stores each captured event as an **activity attached to the\nperson or company entity**, not as a row anywhere.\n\n### Decide whether \"signals\" means triggers or captured events\n\nUsers often call both the watch and each occurrence it captures a \"signal\". Do\nnot decide from the noun or signal type alone. Use the session context to form a\nlikely interpretation, but **do not silently guess**. If the user's wording does\nnot explicitly distinguish the two, ascertain their intent with a short,\nplain-language question before calling either surface: \"Do you mean how many\nJobPost watches are configured, or how many JobPost events were captured?\" You\nmay say which reading seems more likely from the conversation, but contextual\nlikelihood is not confirmation. An explicit earlier statement about triggers or\nevents does count as confirmation.\n\n- Use `clay signals` for **trigger definitions** when the conversation is at the\n  inventory or configuration level: listing, creating, updating, pausing,\n  resuming, scheduling, checking run status, or choosing a destination. In that\n  context, \"how many JobPost signals do I have?\" means count JobPost trigger\n  definitions.\n- Use `clay audiences signals` for **captured events** when the conversation is\n  about results or history: what happened, detections over a period, affected\n  records, an audience/segment, or a trigger's output. In particular, once the\n  session is focused on one specific trigger, the same question — \"how many\n  JobPost signals do I have?\" — usually means how many events that trigger has\n  captured, not how many trigger definitions exist. Resolve its underlying\n  `signal.id` with `clay signals get` when needed, then narrow\n  `clay audiences signals summary` with `--signal-ids`.\n- After the user confirms captured events, reuse the record or audience/segment\n  and time scope already established in the session. If any required scope is\n  still missing, ask for it rather than inventing one.\n\nOnce the intended meaning is clear:\n\n- **Signal questions should use signal-specific surfaces.** Do not use\n  `clay audiences activities` commands to answer signal-event questions; those\n  commands read activity rows and can miss signal-specific event detail.\n- **Read captured events by record or segment.** `clay audiences signals list`\n  returns the full event history for one person or company with `--entity-id`,\n  or full payloads across a saved segment with `--segment-id`. The\n  `signals summary` command groups a segment's counts by signal id and type.\n- **Find matching records with DSL.** Use `records search-ids/search-count --query`\n  with `signals.<type>.exists(...)` — see `queries.md`. To save those criteria as\n  an audience, see `filters.md`, \"Filter by signal activity\".\n- Check captured history through those event relationships. An empty trigger\n  inventory (`clay signals list`) or `signal_summary` field does not prove that\n  no events exist.\n- For which signals exist, what one watches, and why one is not producing\n  events, see the `signals` skill — that is where to start for \"is this\n  audience's signal firing?\"\n\n```bash\nclay audiences signals list --entity-id 123 --entity-type people --since 2026-08-01\nclay audiences signals list --segment-id audseg_abc --since 2026-08-01 --until 2026-08-20 --signal-types JobPost,News\nclay audiences signals summary --segment-id audseg_abc --since 2026-08-01 --signal-types JobPost --signal-ids sig_abc\n```\n\n- Use `signals list --entity-id` when the user names one record. Pass the numeric\n  id from `clay audiences records search-ids`, its `--entity-type`, and an\n  explicit `--since` (and optional `--until`). It returns that record's events newest first;\n  continuation calls repeat `--entity-id` and `--entity-type` with the returned\n  `--cursor`, without time filters.\n- Use `signals list --segment-id` when the event payloads across a saved segment\n  matter. It returns one cursor page with `data`, timestamps, signal id and\n  type, and matched-entity count.\n- Use `signals summary` for totals and first/last activity times. A summary can\n  cover multiple `--signal-types` and optionally narrow to underlying `sig_…`\n  ids with `--signal-ids`.\n- Segment-scoped first-page reads require `--since` and `--signal-types`; bound\n  them with `--until` where possible. Their continuation calls repeat\n  `--segment-id` but pass only `--cursor` and optional `--limit`, without\n  repeating filters.\n- `--since` (inclusive) and `--until` (exclusive) filter on `activityTime` —\n  when the underlying event happened — not `emittedAt`, when the signal event\n  was emitted.\n- `--signal-ids` takes the underlying `signal.id` shown by `clay signals get`,\n  not that command's `td_…` trigger definition id.\n\n## Error codes\n\nEvery command prints JSON on stdout and a typed error envelope on stderr. Exit\ncodes: `0` ok, `2` validation, `3` auth, `4` rate-limit, `5` network, `6`\nnot-found. `3` on an audiences command usually means Audiences is not enabled for\nthe workspace — that is a workspace-config answer for the user, not something to\nretry.\n\n`4` (`rate_limited`) means the workspace reached an Audiences rate limit.\nMost Audiences requests share a workspace budget. `records get` has a separate\n100,000-record allowance per workspace that replenishes at 100,000 records/hour,\ncharged by the number of IDs requested. Activity from another caller can affect when a retry succeeds.\n\nWait `details.retryAfter` seconds before retrying. If the retry is also rate\nlimited, follow its retry delay instead of repeatedly sending the request.\n"
}

SHA-256 of public snapshot: 389fd068e76719c2d6f2920fca1fe70bb29023a7e69e14977c5aba3f0202d4ca