# Audiences > 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. - Skill: `clay-run/audiences` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add clay-run/audiences` - Raw SKILL.md: https://api.skillmd.com/api/skills/clay-run/audiences/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: clay-run (https://skillmd.com/u/clay-run) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/clay-run/audiences --- # Clay Audiences Audiences is Clay's CRM-shaped store of **people** and **companies** (plus deal records). An **audience** — also called a saved segment — is a named filter over one entity type. Nothing is copied into it: it selects records live, so its membership changes as records change. **Audiences is the default home for the workspace's own people and companies.** When a user mentions people, companies, contacts, leads, accounts, customers, deals, or opportunities without naming a surface, they mean these records — start here, not in the tables entry-point skill (a separate surface, right only when the user names a table) and not in `search` (net-new prospects that are not in the workspace yet). Read this before any audiences work. Supporting references: - `answering-data-questions.md` — **read this first for any request to count, find, or filter existing records.** Before filtering a categorical field, call `fields list-values` as described there. Also covers field coverage and when to enrich. - `queries.md` — **read before writing a `--query`.** Audiences DSL grammar, relationship semantics, data or date filters, and server-side sorting for top-N questions. - `filters.md` — writing the filter AST that defines an audience. Read it before you author or edit a filter. - `custom_objects.md` — **deals / opportunities.** Read it before anything that touches them, including vague rankings such as "largest opportunities", "biggest things in our pipeline", or "recent wins", and GTM phrasings: closed-won, closed-lost, open pipeline, deal stage, deal size / ACV / ARR, close date, forecast, win rate, renewal, expansion, churn, "our customers". Deals are read-only. Use the DSL `opportunities` root for deal counts and IDs; use people/company roots when the requested results are contacts/accounts associated with those deals. - The `workflows` skill's `audiences.md` — writing values onto records (the `upsert-audiences-record` action) and triggering a workflow off an audience. **Read with the CLI, write records with the action.** `clay audiences` covers every Audiences primitive — segments, fields, and reading records — but it has no command that writes a field value onto a record. That is the `upsert-audiences-record` action's job. **Net-new people or companies** — not in the workspace yet. When `search` and `routines` are available CLI commands, start in the `searches` skill, then persist via a routine wrapping an upsert workflow (the `workflows` skill's `audiences.md`, then the `routines` skill). **Act on this audience** — pull matching records (`records search-ids` / `get`). When `routines` is an available CLI command, run a routine over them (see the `routines` skill). Ongoing automation (fire when membership changes) is the `workflows` skill's `audiences.md` (`audience_segment` trigger). ## One entity type, three spellings The same entity types are named differently depending on where you are. Get this mapping right up front — it is the most common source of wasted round trips. | CLI `--entity-type` | Filter AST / action `entityType` | Filter `dataPath` root | | ------------------- | -------------------------------- | ----------------------------- | | `people` | `CONTACT` | `contact_entity_field_values` | | `companies` | `ACCOUNT` | `account_entity_field_values` | | `deals` | `CUSTOM` (Opportunity) | `opportunity` | Supported `--entity-type` values by command (all under `clay audiences`): | Commands | Accepted values | Deals support | | ------------------------------------------------------------------------------------------------ | ------------------------------ | ---------------------------------------------------------- | | `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 | | `list`, `create` | `people`, `companies` | Not supported; saved audiences target people or companies | | `fields create`, `fields update`, `fields delete`, `fields segments` | `people`, `companies` | Not supported | | `signals get --entity-id` | `people`, `companies` | Not supported | Use these exact plural values: `person`, `company`, and `deal` are invalid. Commands not listed above do not take `--entity-type`; segment-scoped commands use the saved audience's type. CLI output can also carry `entityType: "deals"`. For filtered deal searches, omit `--entity-type` and use `--query` with the DSL `opportunities` root; read `custom_objects.md` first. Workflow **triggers** use the middle spelling: an `audience_segment` trigger's `segmentId` is the audience id from `clay audiences list`, and its `entityType` is `CONTACT` / `ACCOUNT`, not `people` / `companies`. ## Audiences (saved segments) Prefer dynamic segments: saved audience filters whose membership updates as records start or stop matching the criteria. Use the user’s request and conversation context to determine the filter. Use a fixed cohort with hard coded matching values only when explicitly requested. Read `filters.md` before building the filter. ```bash clay audiences list --entity-type people # id, name, entityType (no filter); 50/page, pass back .cursor clay audiences get # same, plus the full filter AST clay audiences create --entity-type people --name "Missing emails" --filter ./filter.json clay audiences update --name "…" --description "…" --filter ./filter.json clay audiences archive # soft delete, idempotent; records untouched ``` - `create` and `update` take `--filter` as inline JSON, **a file path, or `-` for stdin**. Use a file or stdin for anything non-trivial — inline JSON in a shell triggers an approval prompt and invites quoting mistakes. - `update` replaces the whole filter; there is no partial merge, and entity type is immutable after creation. Omitted flags are left alone. - `get` returns an id-free filter, so `clay audiences get | jq .filter` pipes straight back into `create --filter -` to clone an audience. ## Fields Field ids are what record payloads and filter ASTs key on, and they are scoped to an entity type — every subcommand takes `--entity-type`. ```bash clay audiences fields list --entity-type people # every field: id, name, dataType, fieldType, hidden clay audiences fields list --entity-type people --filter id=email # narrow by id (repeatable, comma-separated) clay audiences fields list --entity-type people --include-system # system fields, hidden by default clay audiences fields create --entity-type people --name "Lead score" --data-type number clay audiences fields update --entity-type people --hidden true clay audiences fields delete --entity-type people clay audiences fields segments --entity-type people # audiences whose filter references the field clay audiences fields list --entity-type deals # deal field definitions clay audiences fields list-values title --entity-type people # distinct values and counts ``` - **Run `fields list` once and save it** (`> /tmp/people-fields.json`), then slice it with `jq`. Re-running it to grep, head, and parse the same output three different ways is pure latency. - `fields list` returns the workspace record-field catalog (system fields excluded) — use those ids for `upsert-audiences-record`. - **Names are not ids.** Account "company name" is `org_name`. Never guess an id from a display name. - **Discover categorical values before filtering.** Use `fields list-values` instead of guessing labels. See `answering-data-questions.md` for value discovery and high-cardinality guidance. - `create` silently uniquifies a taken name (`"Tier (2)"`) — read the returned `name` and `id` rather than assuming the one you passed. - Before `update --data-type` or `delete`, run `fields segments `: a delete rewrites saved filters with those clauses **removed**, changing what those audiences match. Empty `data` means nothing is affected. - Default and system fields reject `--name` and `--data-type` changes and cannot be deleted; `--hidden`, `--order`, and `--description` still work. ### Default field ids Present in every workspace, so you can write a filter against these without listing fields first: - **people** — `name`, `first_name`, `last_name`, `email`, `linkedin_url`, `phone`, `title`, `signal_summary` - **companies** — `org_name`, `domain`, `headquarters_location`, `linkedin_url`, `sfdc_owner_id`, `signal_summary`, `technographics` - **deals** — see `custom_objects.md` `signal_summary` is derived from the signal events a signal has written onto the record, not something you set — to see which signals feed it, use the `signals` skill. Anything else is workspace-defined — get its id from `fields list`. ## Records ```bash clay audiences records search-count --entity-type people --audience-id # count a scope server-side clay audiences records search-ids --entity-type people --audience-id # matching ids, --limit per page + .cursor clay audiences records get --entity-type people --ids 1,2,3 # field values, max 100 ids ``` Scope for both search commands (`--query`, `--audience-id`, and `--filter` are mutually exclusive): - no scope flag → every record of the entity type - `--query ` → preferred for ad-hoc searches; omit `--entity-type` (combining them is an error). Use `count from ...` for `search-count` and `select from ...` for `search-ids`. Read `queries.md` before constructing the query - `--audience-id ` → a saved audience's records - `--filter ` → AST fallback for unsupported DSL constructs, matching exactly what an audience built from that filter would hold Add `--archived` to either to search archived records instead of live ones. **Use `search-count` for "how many".** It counts server-side without fetching every ID. A field's `is_not_null` query (or `NotEmpty` AST filter) checks coverage when relying on unfamiliar data or proposing an enrichment. See `answering-data-questions.md`. **Use `search-ids --query 'select from ... order by desc' --limit N` for top-N people, companies, or deals.** This is the preferred way to answer "Top N" questions: rank server-side and fetch only the N returned IDs for details, without paginating through the full record set or sorting it locally. Before ranking, check the field's `dataType` with `fields list`: numeric questions require a number or currency field, not numeric-looking text. If the type is wrong, recommend fixing the Audiences field type before ranking; do not change it without approval. Sorting supports one same-entity text, number (including currency), or date field. Missing values come last. Sorted results have no cursor, even if more records match; they are not a full export. To count the same scope, use `count from ... where ...` without `order by` or `limit`. Read `queries.md` for grammar, field discovery, limits, and examples. For filtered deal counts and IDs, use `--query` with the `opportunities` root. `--entity-type deals` without a query still covers the whole population; combining it with `--audience-id` or a non-empty `--filter` is a validation error. The `activities` root supports counts; activity IDs are strings and cannot use `search-ids`' numeric pagination. See `queries.md` and `custom_objects.md`. `search-ids` returns ids only — feed them to `records get --ids` in batches of 100 for field values, keyed by field id (unset fields may be omitted). Records not found are omitted rather than erroring. To size a scope, use `search-count`, not a paging loop over `search-ids`. ### Budget the walk before you start it `search-count` first, then decide whether a full walk fits. Both stages spend the same per-command budgets, and the second one dominates: - **ids** — unsorted `search-ids` pages at `--limit` ids per call (default 50, max 10,000). Size it from the count: aim for about 10 calls. - **field values** — `records get` takes 100 ids per call and is charged per id against its hourly budget, so the detail pass costs `count/100` calls that no batching shrinks. You can only make up to 60 calls per minute. When that does not fit your data size, **narrow the scope instead of grinding through it**: tighten the filter — a shorter date window is usually the biggest win, then a single stage, owner, or segment — or read one page and label the answer a sample of that scope. Never start an unbounded paging loop and hope it lands: it spends the workspace's budget and the user gets a stalled turn instead of an answer. ## Segment activities Use `clay audiences activities` when the user asks what happened inside a saved segment, such as recent email or call activity, campaign touches, source mix, or activity volume over a period. ```bash clay audiences activities get --segment-id audseg_abc --since 2026-08-01 --until 2026-08-20 --activity-types call clay audiences activities summary --segment-id audseg_abc --since 2026-08-01 --until 2026-08-20 --activity-types call --sources CLAY_SEQUENCER ``` - Use `activities get` for the raw activity feed. It returns cursor-paginated events for records in the segment. - Use `activities summary` for grouped counts by activity type and source when the user asks for totals, trends, or a quick breakdown instead of individual events. - Bound the first request with `--since` and, when possible, `--until`, `--activity-types`, or `--sources`. These queries can take a few seconds on large segments, so prefer one targeted request over repeated exploratory calls. - It is okay to page through `activities get` with each returned cursor when the user needs the full bounded result set. Continuation requests pass only `--cursor` and optional `--limit`; do not repeat time, activity-type, or source filters with a cursor. Do not loop for freshness or repeatedly rerun broad activity queries without narrowing the request. - Common prompts: "show recent calls for this segment", "summarize email activity since last week", "which sources drove activity for this audience?", "sample the latest campaign activity before I run a workflow". ## Signals Signals write activities onto records. A **signal** on an audience — a watch for job changes, new hires, funding news, job postings — stores each captured event as an **activity attached to the person or company entity**, not as a row anywhere. ### Decide whether "signals" means triggers or captured events Users often call both the watch and each occurrence it captures a "signal". Do not decide from the noun or signal type alone. Use the session context to form a likely interpretation, but **do not silently guess**. If the user's wording does not explicitly distinguish the two, ascertain their intent with a short, plain-language question before calling either surface: "Do you mean how many JobPost watches are configured, or how many JobPost events were captured?" You may say which reading seems more likely from the conversation, but contextual likelihood is not confirmation. An explicit earlier statement about triggers or events does count as confirmation. - Use `clay signals` for **trigger definitions** when the conversation is at the inventory or configuration level: listing, creating, updating, pausing, resuming, scheduling, checking run status, or choosing a destination. In that context, "how many JobPost signals do I have?" means count JobPost trigger definitions. - Use `clay audiences signals` for **captured events** when the conversation is about results or history: what happened, detections over a period, affected records, an audience/segment, or a trigger's output. In particular, once the session is focused on one specific trigger, the same question — "how many JobPost signals do I have?" — usually means how many events that trigger has captured, not how many trigger definitions exist. Resolve its underlying `signal.id` with `clay signals get` when needed, then narrow `clay audiences signals summary` with `--signal-ids`. - After the user confirms captured events, reuse the record or audience/segment and time scope already established in the session. If any required scope is still missing, ask for it rather than inventing one. Once the intended meaning is clear: - **Signal questions should use signal-specific surfaces.** Do not use `clay audiences activities` commands to answer signal-event questions; those commands read activity rows and can miss signal-specific event detail. - **Read captured events by record or segment.** `clay audiences signals get` returns the full event history for one person or company with `--entity-id`, or full payloads across a saved segment with `--segment-id`. The `signals summary` command groups a segment's counts by signal id and type. - **Filters can select on them.** "Companies with a job posting in the last 30 days" is a `signal_events` predicate — see `filters.md`, "Filter by signal activity". - For which signals exist, what one watches, and why one is not producing events, see the `signals` skill — that is where to start for "is this audience's signal firing?" ```bash clay audiences signals get --entity-id 123 --entity-type people --days-lookback 30 clay audiences signals get --segment-id audseg_abc --since 2026-08-01 --until 2026-08-20 --signal-types JobPost,News clay audiences signals summary --segment-id audseg_abc --since 2026-08-01 --signal-types JobPost --signal-ids sig_abc ``` - Use `signals get --entity-id` when the user names one record. Pass the numeric id from `clay audiences records search-ids`, its `--entity-type`, and an explicit `--days-lookback`. It returns that record's events newest first; continuation calls repeat all three scope flags and pass the returned `--cursor`. - Use `signals get --segment-id` when the event payloads across a saved segment matter. It returns one cursor page with `data`, timestamps, signal id and type, and matched-entity count. - Use `signals summary` for totals and first/last activity times. A summary can cover multiple `--signal-types` and optionally narrow to underlying `sig_…` ids with `--signal-ids`. - Segment-scoped first-page reads require `--since` and `--signal-types`; bound them with `--until` where possible. Their continuation calls repeat `--segment-id` but pass only `--cursor` and optional `--limit`, without repeating filters. - `--since` (inclusive) and `--until` (exclusive) filter on `activityTime` — when the underlying event happened — not `emittedAt`, when the signal event was emitted. - `--signal-ids` takes the underlying `signal.id` shown by `clay signals get`, not that command's `td_…` trigger definition id. ## Error codes Every command prints JSON on stdout and a typed error envelope on stderr. Exit codes: `0` ok, `2` validation, `3` auth, `4` rate-limit, `5` network, `6` not-found. `3` on an audiences command usually means Audiences is not enabled for the workspace — that is a workspace-config answer for the user, not something to retry. `4` (`rate_limited`) means the workspace spent its request budget for that one command. The budget is per command and shared by everyone in the workspace, so a `fields list` loop cannot starve `search-count`. It defaults to 60 calls/minute and a workspace can be raised above that, so read `details.limit` off the error rather than assuming the default. Sleep `details.retryAfter` seconds and carry on. A request-rate rejection costs no budget and writes nothing, so repeating the identical call — including a `create` or `update` — once the wait is over is safe. `records get` carries a second budget: an hourly one charged per record id it returns, which batching does not reduce. Read its 429s more carefully than the rest: - `details.limit` is records/hour (default 100,000), not calls/minute, and the message says "Hourly records limit" rather than "Too many requests". - The rejected call **did** spend a request token — that one is not refunded — so the wait it asks for can end in a second 429, this time from the per-minute rate. Back off again rather than reading it as a failure. That budget exists to prevent data exfiltration, so be conservative: before pulling a large set, check whether a sample of records answers the request.