Updating an Audience's Filter with the Clay CLI

Replace a saved segment's filter in place (without changing its id, name, or the signals and campaigns already pointed at it), using Clay's real audiences update command.

What you will build

An in-place filter replacement on an existing audience, confirmed by reading it back.

clay audiences update <audienceId> --filter <AST>
    ↓
{ id (unchanged), name (unchanged), filter (replaced), updatedAt }

AI Prompt

Using the Clay CLI, replace an existing audience's filter without recreating
the audience.

Requirements:
- `clay audiences update <audienceId> [--name <name>] [--description <text>]
  [--filter <json|file|->]` -- only the fields you pass change.
- --filter REPLACES the entire filter AST outright. There is no partial
  filter merge -- passing a filter with fewer conditions than before drops
  the missing ones entirely, it does not layer on top of the existing
  filter.
- The update reads the audience, applies the passed fields, and writes the
  whole thing back -- concurrent edits are last-write-wins.
- An audience's entity type CANNOT be changed after creation -- --filter
  must still describe records of the same entity type the audience was
  created with.
- The audience's id is stable across the update, so anything referencing it
  by id (a signal's segmentIds, a campaign's leadBaseSegmentId) keeps
  working against the new filter with no changes on their end.
- 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. Read the current filter

clay audiences get audseg_0tl84p1ZQ8RRShHSAdX | jq .filter

2. Replace it with a different condition

clay audiences update audseg_0tl84p1ZQ8RRShHSAdX --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, the audience's id and name are unchanged, only filter and updatedAt moved:

{
  "id": "audseg_0tl84p1ZQ8RRShHSAdX",
  "name": "TPC CLI Docs Test Companies",
  "filter": {"type": "GroupOp", "combinationMode": "And", "items": [{"type": "BinOp", "key": "industry", "operator": "Contain", "value": "Software", "entityType": "ACCOUNT"}]},
  "updatedAt": "2026-09-12T00:19:16.045Z"
}

3. Rename without touching the filter

clay audiences update audseg_0tl84p1ZQ8RRShHSAdX --name "Software companies"

Passing only --name leaves the filter exactly as it was, confirmed live: --filter is the only flag that touches filter content.

Verify the result

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

clay audiences update audseg_0tl84p1ZQ8RRShHSAdX --filter '{...}'

Expected: The audience's filter is replaced in place; id and name are unchanged, and a subsequent clay audiences get confirms the new filter is what search-count/search-ids now evaluate against.

How it works

Keeping an audience's id stable across a filter update is the whole point of this command existing separately from delete-and-recreate: every signal watching this audience by segmentIds, and every campaign pointing at it via leadBaseSegmentId, keeps working unchanged after the underlying selection criteria shift. The tradeoff is that --filter is a full replacement, not a merge: there's no way to add one more condition without resending the whole tree.

Common issues

Expecting --filter to add a condition rather than replace the tree

Cause: assuming an "update" command merges partial input, the way audiences fields update does for field properties.

Fix: --filter on audiences update replaces the ENTIRE filter. Read the current filter first, edit it locally, and resend the whole thing.

Trying to change entity type via update

Cause: assuming any property of an audience is patchable.

Fix: entity type is fixed at creation. Create a new audience instead.

Next steps

• Before changing a filter, check what references the audience: a signal by its segmentIds, a campaign by leadBaseSegmentId.
• Verify the new filter's real match count with clay audiences records search-count --audience-id <id> --entity-type <type>.

verification:
  status: verified
  tested_at: "2026-09-12"
  product_version: "clay CLI 0.19.0"
  command: "clay audiences update audseg_0tl84p1ZQ8RRShHSAdX --filter '{...}'"
  expected_result: "The audience's filter is replaced in place; id and name are unchanged, and a subsequent clay audiences get confirms the new filter is what search-count/search-ids now evaluate against."