Discovering Real Audience Field Values with the Clay CLI

clay audiences fields list-values returns the distinct values actually stored in a field across every record of an entity type, with a count per value. It answers "what does this field really contain" before writing a filter against it, and an empty result is a real, valid answer, not an error.

What you will build

A list-values call against a text field and against a field with no populated records, to show both a real distinct-value list and the legitimate empty case.

clay audiences fields list --entity-type people        (find a field id)
    ↓
clay audiences fields list-values <fieldId> --entity-type people

AI Prompt

Using the Clay CLI, discover the real distinct values stored in an Audiences field before
writing a filter against it.

Requirements:
- `clay audiences fields list-values <fieldId> --entity-type people|companies|deals --limit <n>`.
- Only queryable text, number, and date fields are supported. Boolean, related, list, and
  unmapped fields are not.
- Output is `{ "data": [{ "value", "count" }], "truncated": <boolean> }`, ordered by count
  descending then value ascending. Missing values form a single null group.
- An empty data array means there are no records holding a value for that field in this
  workspace, which is a legitimate result, not evidence the field id is wrong.
- --limit defaults to 50 and can go up to 24999; there is no cursor, so a truncated result
  is resolved by raising --limit, not by paging.
- 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. List field ids for an entity type

clay audiences fields list --entity-type companies

Real output, trimmed:

{
  "data": [
    { "id": "org_name", "name": "Company name" },
    { "id": "industry", "name": "Industry" },
    { "id": "employee_count", "name": "Employee count" }
  ]
}

2. Read distinct values for a field

clay audiences fields list-values org_name --entity-type companies --limit 10

Real output, from a workspace with no synced company records yet:

{ "data": [], "truncated": false }

Verify the result

clay audiences fields list-values <fieldId> --entity-type companies --limit 10

Expected: an object with data (possibly empty) and truncated, never an error, for any field id returned by audiences fields list.

How it works

The command counts every record of the given entity type that holds a value for the field, groups identical values, and orders the result by how common each value is. Because it reads the full record set rather than a sample, the result reflects the workspace's actual data at the moment of the call, not a cached schema definition. A workspace or field with no populated records simply returns an empty data array with truncated: false, the same shape a populated field would return with zero matches.

Common issues

An empty result does not mean the field id is invalid

A field that exists but has no records holding a value returns the same empty data array as a field with genuinely no data. Cross-check with clay audiences records get on a known record before concluding a field id is wrong.

truncated: true means raise --limit, not paginate

There is no cursor for this command. If truncated is true, increase --limit (up to 24999) and re-run, rather than looking for a next-page token.

Next steps

• Finding Which Audiences Reference a Field

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay audiences fields list-values org_name --entity-type companies --limit 10"
  expected_result: "Returns { data: [], truncated: false } for a real field with no populated records, rather than an error."

Related Articles

• Discovering Real Audience Fields with the Clay CLI
• Searching, Counting, and Fetching Audience Records with the Clay CLI
• Finding Which Audiences Reference a Field with the Clay CLI