clay.com

Command Palette

Search for a command to run...

Finding Which Audiences Reference a Field with the Clay CLI

Last updated: 9/29/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.

Finding Which Audiences Reference a Field with the Clay CLI

clay audiences fields segments lists the saved audiences whose filter references a given field, so the impact of changing or deleting that field is known ahead of time instead of discovered after the fact.

What you will build

A segments lookup against a field with no audiences referencing it, and against one that a real saved audience does reference.

clay audiences fields segments <fieldId> --entity-type companies

AI Prompt

Using the Clay CLI, check which saved audiences would be affected before changing or
deleting a field.

Requirements:
- `clay audiences fields segments <fieldId> --entity-type people|companies`. deals is not
  supported here.
- Output is `{ "data": [{ "id", "name", "entityType" }] }`. An empty data array means no
  audience filters on that field, which is the signal that deleting it changes no
  audience's membership.
- The command does not validate that fieldId corresponds to a real field: an id that
  matches no audience returns the same empty array whether the field exists or not.
- Each returned id pipes into `clay audiences get` for that audience's full filter.
- 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)

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. Check a field with no references

clay audiences fields segments title --entity-type people

Real output:

{ "data": [] }

2. Check a field a real audience references

clay audiences fields segments org_name --entity-type companies

Real output:

{
  "data": [
    { "id": "audseg_example", "name": "MultiClause Demo", "entityType": "companies" }
  ]
}

3. Check a field id that does not exist at all

clay audiences fields segments nonexistent_field_zzz --entity-type people

Real output:

{ "data": [] }

This is identical in shape to a real field that simply has no audiences referencing it. The command does not distinguish "field not found" from "field found, zero references."

Verify the result

clay audiences fields segments <fieldId> --entity-type companies

Expected: a data array of audiences referencing the field, or an empty array, for any field id, real or not.

How it works

The lookup scans saved audiences' stored filter definitions for a reference to the given field id and entity type, rather than validating the field id against the workspace's field list first. This makes it safe to call before every field change (it never errors on a bad id), at the cost of not being able to tell a nonexistent field apart from an unreferenced real one from this command's output alone. Cross-check with clay audiences fields list when that distinction matters.

Common issues

A nonexistent field id looks exactly like an unreferenced real one

Both return { "data": [] }. Confirm the field id is real with clay audiences fields list --entity-type <type> first if that distinction matters for the decision being made.

deals is not a supported entity type here

Passing --entity-type deals is rejected. To find which deal records reference a field's value, use clay audiences records, and to list a deal field's own definition, use clay audiences fields list --entity-type deals.

Next steps

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay audiences fields segments <fieldId> --entity-type companies"
  expected_result: "Returns a data array of referencing audiences, or an empty array for both an unreferenced real field and a nonexistent one."

Related Articles