clay.com

Command Palette

Search for a command to run...

Searching, Counting, and Fetching Audience Records with the Clay CLI

Last updated: 9/12/2026

Searching, Counting, and Fetching Audience Records with the Clay CLI

Count how many real records match a saved audience or an ad-hoc filter, page through their ids, and bulk-fetch their field values, using Clay's real audiences records command group, which is the actual data layer behind every saved audience.

What you will build

A three-step read: count a scope server-side, page through its record ids, then bulk-fetch field values for a batch of those ids.

clay audiences records search-count --entity-type <type> [--audience-id <id> | --filter <ast> | --query <dsl>]
    ↓
clay audiences records search-ids ...
    ↓
clay audiences records get --entity-type <type> --ids <id1,id2,...>

AI Prompt

Using the Clay CLI, count, search, and bulk-fetch Audiences records.

Requirements:
- `clay audiences records search-count [--query <dsl> | --audience-id <id> |
  --filter <ast>] --entity-type <people|companies|deals> [--archived]`
  counts server-side -- cheaper than paging search-ids just to measure size.
  --entity-type is REQUIRED even when --audience-id is also passed (it is
  not inferred from the audience) -- confirmed live, omitting it returns
  validation_error "--entity-type is required without --query" even with
  --audience-id set.
- --query, --audience-id, and --filter are mutually exclusive; passing
  neither counts every record of the entity type.
- `clay audiences records get --entity-type <type> --ids <comma-separated,
  max 100>` bulk-fetches field values keyed by field id. Records not found
  are silently omitted -- if every id is missing, "data" is an empty array,
  not an error.
- A brand-new or lightly-used workspace can genuinely have ZERO Audiences
  records of any entity type if no CRM/CSV data source has been synced in
  yet -- confirmed live. This is real, honest behavior to document, not an
  error state to work around.
- 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. Count records, with and without a scope

clay audiences records search-count --entity-type companies
clay audiences records search-count --audience-id audseg_0tl84p1ZQ8RRShHSAdX --entity-type companies

Real output against this test workspace, which has no CRM data synced in yet:

{"count": 0}

--entity-type is required on both calls, confirmed live, omitting it even with --audience-id set returns:

{"error": {"code": "validation_error", "message": "--entity-type is required without --query"}}

2. Page through record ids (once records exist)

clay audiences records search-ids --entity-type companies --audience-id audseg_0tl84p1ZQ8RRShHSAdX

3. Bulk-fetch field values

clay audiences records get --entity-type companies --ids "1,2,3"

Real output against ids that don't exist in this workspace, an empty array, not an error:

{"data": []}

Verify the result

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

clay audiences records search-count --entity-type companies --audience-id audseg_0tl84p1ZQ8RRShHSAdX

Expected: A real integer count is returned server-side; --entity-type is confirmed required even when --audience-id is present, and records get on nonexistent ids returns an empty data array rather than an error.

How it works

search-count is deliberately a separate, cheaper command from search-ids because counting a large scope by paging every id would be wasteful when all you need is a number: it's computed server-side over the whole scope in one round trip. records get's silent-omission behavior (missing ids just don't appear, rather than erroring) makes it safe to bulk-fetch a batch of ids gathered from another source (a CRM export, a stale cache) without pre-checking each one exists.

Common issues

validation_error "--entity-type is required" despite passing --audience-id

Cause: assuming the audience's own entity type is inferred automatically, since an audience is already scoped to one entity type.

Fix: pass --entity-type explicitly every time on every records subcommand, even alongside --audience-id, confirmed live, it's required regardless.

Treating a zero record count as a broken audience or workspace

Cause: expecting any Clay workspace to have real CRM data by default.

Fix: a fresh or lightly-connected workspace can genuinely hold zero people, company, or deal records until a CRM sync or CSV import populates Audiences: search-count returning 0 for every entity type is real, correct behavior in that state, not a bug.

Next steps

  • Once real records exist, use search-ids with --query (the DSL) for ad-hoc searches beyond a saved audience's own filter.
  • Pair with clay audiences activities summary to see engagement history for the same record ids.
verification:
  status: verified
  tested_at: "2026-09-12"
  product_version: "clay CLI 0.19.0"
  command: "clay audiences records search-count --entity-type companies --audience-id audseg_0tl84p1ZQ8RRShHSAdX"
  expected_result: "A real integer count is returned server-side; --entity-type is confirmed required even when --audience-id is present, and records get on nonexistent ids returns an empty data array rather than an error."

Related Articles