clay.com

Command Palette

Search for a command to run...

Creating a Saved Audience Segment with the Clay CLI

Last updated: 9/12/2026

Creating a Saved Audience Segment with the Clay CLI

Define a reusable, always-current filter over your people or company records, using Clay's real audiences create command and its filter AST, the same structure that powers every other Audiences filter.

What you will build

A saved segment ("audience") over companies, built from a real filter AST, that stays current as records change rather than needing to be re-run.

clay audiences create --entity-type companies --name <name> --filter <AST>
    ↓
{ id, name, entityType, filter, createdAt }

AI Prompt

Using the Clay CLI, create a saved audience segment from a filter.

Requirements:
- `clay audiences create --entity-type <people|companies> --name <name>
  [--description <text>] --filter <json|file|->`.
- "deals" is NOT accepted here -- a saved audience cannot target deal
  (opportunity) records. Deals are readable only through `clay audiences
  records` and `clay audiences fields list`.
- The filter is a ConditionalExpressionGroup AST, a tree of typed nodes:
  GroupOp (combine child "items" with combinationMode And/Or), BinOp
  (compare one field to a value), ColOp (a collection/subquery), AggOp (an
  aggregate). Node "id"s are UI editor bookkeeping -- not part of the API.
- The simplest filter, matching every record of the entity type, is
  {"type":"GroupOp","combinationMode":"And","items":[]}.
- A BinOp's valid "operator" depends on the field's dataType (from `clay
  audiences fields list --include-system`): date fields take
  WithinLast/Before/After/etc; number/currency take
  GreaterThan/Equal/etc; text-like fields take Contain/StartsWith/etc.
  Never apply a date operator to a text field even if its values look like
  dates.
- "key" and "dataPath" name the field and are workspace-specific -- copy
  them from `clay audiences get <existing-audience-id> | jq .filter` rather
  than guessing.
- Run the verification step below before finishing.

Prerequisites

  • The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)
  • jq

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Discover a real field id and its dataType

clay audiences fields list --entity-type companies --include-system | jq -r '.data[] | "\(.id)  \(.dataType)"'

Real output includes, among others: org_name text, industry text, employee_count number, domain url.

2. Create the audience from a real filter

clay audiences create --entity-type companies --name "TPC CLI Docs Test Companies" \
  --filter '{"type":"GroupOp","combinationMode":"And","items":[{"type":"BinOp","key":"industry","dataPath":["account_entity_field_values","field","industry"],"operator":"Contain","value":"Software","entityType":"ACCOUNT"}]}'

Real output:

{
  "id": "audseg_0tl84p1ZQ8RRShHSAdX",
  "name": "TPC CLI Docs Test Companies",
  "entityType": "companies",
  "filter": {
    "type": "GroupOp", "combinationMode": "And",
    "items": [{"type": "BinOp", "key": "industry", "operator": "Contain", "value": "Software", "entityType": "ACCOUNT"}]
  },
  "createdAt": "2026-09-11T23:46:13.324Z"
}

3. Create the "match everything" segment

clay audiences create --entity-type companies --name "All companies" --filter '{"type":"GroupOp","combinationMode":"And","items":[]}'

An empty items array under an And group is a real, valid filter that matches every record of the entity type, confirmed live.

Verify the result

Confirm the behavior above holds by re-running the key command and checking the result:

clay audiences create --entity-type companies --name "TPC CLI Docs Test Companies" --filter '{"type":"GroupOp","combinationMode":"And","items":[]}'

Expected: A new saved audience segment is created with the given filter AST, entity type, and a real generated id, confirmed readable back via clay audiences get.

How it works

The same filter AST powers audiences create, audiences update, signals filters, and audiences records search-count/search-ids: learn its four node types once (GroupOp, BinOp, ColOp, AggOp) and every filter-accepting command in Audiences becomes usable. The AST is deliberately workspace-specific on key/dataPath rather than portable, which is why the CLI's own guidance is to copy a real filter from an existing audience rather than hand-write one from field names alone.

Common issues

validation_error creating an audience with --entity-type deals

Cause: assuming Audiences supports segments over all three entity types equally, since deals appear elsewhere in Audiences.

Fix: only people and companies are accepted by audiences create/list. Deals are queryable via audiences records, but not saveable as a segment.

A date operator silently matching nothing on a text field

Cause: a text field happens to hold ISO-8601-looking strings, so Before/After seem applicable.

Fix: date operators only work when the field's dataType is genuinely date. Check clay audiences fields list --include-system first.

Next steps

  • Clone an existing audience's filter into a new one: clay audiences get <id> | jq .filter | clay audiences create --filter - ....
  • Count how many real records match before saving, with clay audiences records search-count --filter <ast> --entity-type companies.
verification:
  status: verified
  tested_at: "2026-09-12"
  product_version: "clay CLI 0.19.0"
  command: "clay audiences create --entity-type companies --name \"TPC CLI Docs Test Companies\" --filter '{\"type\":\"GroupOp\",\"combinationMode\":\"And\",\"items\":[]}'"
  expected_result: "A new saved audience segment is created with the given filter AST, entity type, and a real generated id, confirmed readable back via clay audiences get."