Using the Audiences DSL Query Syntax with the Clay CLI

Search, count, and page through Audiences records with a plain-text query instead of hand-building a filter AST, using the DSL accepted by --query. The DSL's root verb differs by command in a way that isn't obvious from the flag name alone.

What you will build

The same real scope queried three ways: counted, listed as ids, and rejected with a real error when it references a field that doesn't exist.

clay audiences records search-count --query 'count from companies where ...'
clay audiences records search-ids   --query 'select from companies where ...'

AI Prompt

Using the Clay CLI, query Audiences records with the DSL instead of a filter
AST.

Requirements:
- `--query` is accepted by `search-count`, `search-ids`, and `records get`'s
  sibling commands, and is preferred over `--filter` for ad-hoc searches.
  The DSL's root verb is command-specific:
  - `search-count` requires "count from <root>", e.g. "count from
    opportunities". Using "select from ..." here is rejected with
    validation_error: "Expected a count query. Use count from <root>...".
  - `search-ids` (and other listing commands) require "select from <root>"
    instead. The two verbs are not interchangeable between commands.
- Valid roots: people, companies, opportunities (deals), and activities
  (count only).
- A `where` clause referencing a field that doesn't exist is rejected with a
  specific, real error naming the field and entity: "Unknown DSL field
  '<name>' for accounts", rather than a silent zero-match result.
- --query, --audience-id, and --filter are mutually exclusive on every
  command that accepts them.
- 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. Use the wrong root verb, and see the real error

clay audiences records search-count --query 'select from companies'

Real output:

{"error": {"code": "validation_error", "message": "Expected a count query. Use count from <root>, for example count from opportunities."}}

2. Use the correct verb for search-count

clay audiences records search-count --query 'count from companies'
clay audiences records search-count --query 'count from companies where industry contains "Software"'

Real output for both, showing a zero count in this workspace:

{"count": 0}

3. Use select from for search-ids

clay audiences records search-ids --query 'select from companies where industry contains "Software"'

Real output:

{"data": []}

4. Reference a nonexistent field

clay audiences records search-count --query 'count from companies where bogus_field = 1'

Real output, a specific, actionable error rather than a silent empty result:

{"error": {"code": "validation_error", "message": "Unknown DSL field 'bogus_field' for accounts"}}

Verify the result

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

clay audiences records search-count --query 'count from companies' && clay audiences records search-ids --query 'select from companies'

Expected: search-count accepts only a count from <root> query and rejects select from ... with a validation_error naming the expected verb; search-ids accepts select from <root> for the same underlying scope; an unknown field name in a where clause errors by name rather than silently matching nothing.

How it works

The DSL's root verb mirrors what each command returns: a count command parses a "count" query, and a listing command parses a "select" query, rather than sharing one generic query grammar across both. Each command's accepted query is self-describing in this way, since the verb indicates what kind of command it is, though a query cannot be copied verbatim between search-count and search-ids.

Common issues

Copy-pasting a select from query into search-count

Both commands accept --query with what looks like the same underlying grammar, but the root verb differs: use count from for search-count and select from for search-ids and similar listing commands. The error message names the expected verb when the wrong one is used.

Assuming a typo'd field name just matches nothing

Many search systems silently return zero results for an unrecognized field name. The Audiences DSL instead validates field names against the entity's schema and returns an error naming the field (Unknown DSL field '<name>') rather than silently matching nothing. A genuine zero-result query and a query with an invalid field name produce different, distinguishable results.

Next steps

• Use clay audiences fields list --entity-type companies to confirm real field names before writing a where clause against them.
• Prefer the DSL over hand-built filter ASTs for ad-hoc, one-off searches; keep filter ASTs for anything you're saving as a reusable audience.

verification:
  status: verified
  tested_at: "2026-09-21"
  product_version: "clay CLI 1.2.0"
  command: "clay audiences records search-count --query 'count from companies where industry contains \"Software\"'"
  expected_result: "search-count requires the 'count from' root verb and rejects 'select from' with a real validation_error naming the expected form; an unknown field in a where clause errors by name rather than silently returning zero."