Summarizing Audience Activity with the Clay CLI

Get activity counts grouped by type, subtype, and source for the records in a saved audience, using Clay's real audiences activities summary command, which requires a real time window even though nothing in its flag names says so.

What you will build

A scoped activity summary for one audience segment over an explicit time range.

clay audiences activities summary --segment-id <id> --since <datetime> --activity-types <types>
    ↓
{ data: [{ activityType, source, activityCount, matchedEntityCount, firstActivityAt, lastActivityAt }], segmentSnapshotAt }

AI Prompt

Using the Clay CLI, summarize Audiences activity for a saved segment.

Requirements:
- `clay audiences activities summary --segment-id <id> --since <ISO
  datetime> --activity-types <comma-separated> [--until <datetime>]
  [--sources <comma-separated>]`.
- --since and --activity-types are BOTH REQUIRED despite neither being
  marked "(required)" in the flag list -- confirmed live, omitting either
  one returns a validation_error naming the missing flag. --until defaults
  to now.
- activity-types enum: call, email, task, meeting, transcript,
  external_membership, message, campaign_status, other, event,
  workflow_run, custom.
- Output groups by activityType + source, each with its own count and
  first/last-seen timestamps -- not a flat total.
- On a segment with no matching activity in the window, "data" is a real
  empty array and "segmentSnapshotAt" can be null -- this is honest,
  correct output, not an error.
- Also see `clay audiences activities get` for the raw, ungrouped event
  list behind this summary.
- 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. Try the command with only --segment-id

clay audiences activities summary --segment-id audseg_0tl84p1ZQ8RRShHSAdX

Real output, --since is required despite not appearing marked required in the help text:

{"error": {"code": "validation_error", "message": "required option '--since <datetime>' not specified"}}

2. Add --since, still missing one flag

clay audiences activities summary --segment-id audseg_0tl84p1ZQ8RRShHSAdX --since 2026-01-01T00:00:00Z

Real output, --activity-types is required too:

{"error": {"code": "validation_error", "message": "required option '--activity-types <types>' not specified"}}

3. The real, complete call

clay audiences activities summary --segment-id audseg_0tl84p1ZQ8RRShHSAdX --since 2026-01-01T00:00:00Z --activity-types email,call,meeting

Real output against a segment with no recorded activity in this window:

{"data": [], "segmentSnapshotAt": null}

An empty data array and a null snapshot timestamp are the honest, correct response for a segment with zero matching activity, not an error.

Verify the result

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

clay audiences activities summary --segment-id audseg_0tl84p1ZQ8RRShHSAdX --since 2026-01-01T00:00:00Z --activity-types email,call,meeting

Expected: --since and --activity-types are confirmed required via real validation_error responses when omitted; the complete call returns a real (empty, in this workspace) data array plus segmentSnapshotAt rather than erroring.

How it works

activities summary groups by activityType + source rather than returning one flat total, because a workspace typically pulls activity from more than one connected source (a CRM sync, a sequencer, an imported call log) and mixing them into one number would hide which channel is actually driving engagement. The two required-but-unmarked flags (--since, --activity-types) exist because summarizing "all activity of every type, forever" over a large workspace would be an expensive, unbounded query: the CLI forces you to scope both dimensions explicitly.

Common issues

validation_error on flags that don't show "(required)" in --help

Cause: the help text's option list doesn't visually flag --since/--activity-types as mandatory the way an argument would be.

Fix (confirmed live): both are enforced as required even though the flag listing doesn't say so. Always pass both.

Reading an empty data array as a broken segment

Cause: expecting any real audience to have some activity history.

Fix: zero activity in the requested window is a legitimate, correctly-reported state: widen --since/--until or broaden --activity-types if you expected results.

Next steps

• Use clay audiences activities get for the raw per-event list behind a summary row.
• Pair with clay audiences signals summary to see detected job-change/news/intent events alongside CRM activity for the same segment.

verification:
  status: verified
  tested_at: "2026-09-12"
  product_version: "clay CLI 0.19.0"
  command: "clay audiences activities summary --segment-id audseg_0tl84p1ZQ8RRShHSAdX --since 2026-01-01T00:00:00Z --activity-types email,call,meeting"
  expected_result: "--since and --activity-types are confirmed required via real validation_error responses when omitted; the complete call returns a real (empty, in this workspace) data array plus segmentSnapshotAt rather than erroring."