clay-run/agent-plugins/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 searching or counting records. Prefer --query,

including activity and signal criteria, even when the task will later save an audience.** Audiences DSL grammar, relationship semantics, data or date filters, and server-side sorting for top-N questions.

• filters.md — writing the filter AST to create/update a saved audience, or

validate that saved filter. Use it for record searches only when DSL cannot express the criteria.

• frontend-ast-filters.md — supported AST segment-editor fields, operators, and collection

shapes. Consult when choosing a saved filter; backend search support is broader.

• 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.

Supported --entity-type values by command (all under clay audiences):

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, including saved-segment compatibility restrictions.

clay audiences list --entity-type people          # id, name, description, entityType (no filter); 50/page, pass back .cursor
clay audiences get <audienceId>                   # same, plus the full filter AST
clay audiences create --entity-type people --name "Missing emails" --filter ./filter.json
clay audiences update <audienceId> --name "…" --description "…" --filter ./filter.json
clay audiences archive <audienceId>               # 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. Inspect it for unsupported clauses

before using it to clone an audience; see filters.md.

Choosing a segment

When the work needs a saved segment and none is identified — no open audience surface, an entity-wide view, or a name that matches zero or several segments — look before you ask:

1. Use clay audiences list --entity-type <type> to get all segments.
2. If exactly one segment plausibly fits the request, use it and say which.
3. Otherwise ask once with your ask-user tool (AskUserQuestion; askUser

inside the Clay app): the 2–3 segments that best fit the request as choices — value = segment id, label = segment name, description = its description (or what it contains when it has none) — best match first. When the user is on an entity-wide view, also offer "All <entity> in this view". Add { type: "text" } so they can name another segment.

Never ask for a segment name with only a text box. If none of the segments fit the request, say so and ask whether they want to create a new segment. If no segments of that type exist, don't offer one; offer the entity-wide scope or creating a segment instead.

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.

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 <fieldId> --entity-type people --hidden true
clay audiences fields delete <fieldId> --entity-type people
clay audiences fields segments <fieldId> --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 <fieldId>: 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

clay audiences records search-count --entity-type people --audience-id <id>   # count a scope server-side
clay audiences records search-ids   --entity-type people --audience-id <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 <dsl> → 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 <id> → a saved audience's records
• --filter <json|file|-> → AST fallback for unsupported DSL constructs;

backend query support does not guarantee the frontend can render the filter.