Reading Signal Events for Audience Records with the Clay CLI

Read the raw signal events (job changes, news, topic intent) detected for records in a saved audience segment, using Clay's real audiences signals get/summary, which is distinct from the top-level signals command group that manages signal definitions.

What you will build

A segment-scoped read of real signal events in a time window, filtered by type, plus the grouped summary form.

clay audiences signals get --segment-id <id> --since <datetime> --signal-types <types>
    ↓
{ data: [{ eventId, signalId, signalType, emittedAt, data }], cursor?, segmentSnapshotAt }

clay audiences signals summary --segment-id <id> --since <datetime> --signal-types <types>
    ↓
{ data: [{ signalId, signalType, signalEventCount, firstActivityAt, lastActivityAt }] }

AI Prompt

Using the Clay CLI, read signal events for records in an audience segment.

Requirements:
- `clay audiences signals get` reads one of two scopes; choose exactly one:
  segment scope (--segment-id, requiring --since and --signal-types on the
  first page; --until defaults to now) or entity scope (--entity-id +
  --entity-type + --days-lookback, required on every page since entity
  reads don't paginate the same window). Entity-scoped events omit
  matchedEntityCount and segmentSnapshotAt, and are ordered newest first.
- `clay audiences signals summary` is segment-scoped only, and --since plus
  --signal-types are both required (no entity-scoped summary exists).
- Signal type enum for both: FakeSignal, JobChange, JobPost,
  WebsiteVisitorTracking, NewHire, Promotion, News, Custom,
  LinkedinPostMentions, PersonTopicIntent, CompanyTopicIntent.
- --signal-ids filters to specific underlying signals. It takes the sig_...
  id shown as signal.id by `clay signals get`, not the td_... trigger
  definition id that command itself accepts.
- entity-type values are plural: people, companies, not person/company.
  deals is not supported by either command.
- The event window (--since to --until) cannot exceed 365 days.
- On a segment/entity with no matching events, "data" is a real empty array
  and "segmentSnapshotAt" can be null. This is correct output, not an error.
- 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. Read segment-scoped events

clay audiences signals get --segment-id audseg_0tl84p1ZQ8RRShHSAdX --since 2026-01-01T00:00:00Z --signal-types JobPost,News,CompanyTopicIntent

Real output against a segment with no matching events in this window:

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

2. Read the grouped summary form

clay audiences signals summary --segment-id audseg_0tl84p1ZQ8RRShHSAdX --since 2026-01-01T00:00:00Z --signal-types JobPost,News,CompanyTopicIntent

Real output:

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

3. Read entity-scoped events instead

clay audiences signals get --entity-id 1 --entity-type companies --days-lookback 30

Real output, the same empty shape, minus segmentSnapshotAt (entity scope never returns it):

{"data": []}

4. Narrow to specific underlying signals

clay audiences signals get --segment-id audseg_0tl84p1ZQ8RRShHSAdX --since 2026-01-01T00:00:00Z --signal-types News --signal-ids sig_0tlqaurE5umZgPaA62e

--signal-ids takes the sig_... id from signal.id in clay signals get's output. Passing the td_... trigger definition id instead silently matches nothing rather than erroring, since it simply won't equal any real signalId.

Verify the result

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

clay audiences signals get --segment-id audseg_0tl84p1ZQ8RRShHSAdX --since 2026-01-01T00:00:00Z --signal-types JobPost,News,CompanyTopicIntent

Expected: a real data array (empty in this workspace) and segmentSnapshotAt are returned for segment scope; entity scope returns data only, with no error, for a record with no detected events in the lookback window.

How it works

This command reads the same signal events signals list's destination tables or audience activity feeds are built from, but scoped directly to a segment or a single record rather than requiring you to already know which signal produced them. The underlying signal (sig_...) is the entity that emits events, while the trigger definition (td_...) is the user-facing configuration wrapper around it. signals get/pause/delete operate on the wrapper, while this command's --signal-ids filters on the underlying emitter.

Common issues

Passing a trigger definition id (td_...) to --signal-ids

The td_... id is what most commands in the signals group accept, making it the natural one to reach for. --signal-ids instead wants the underlying sig_... id from signal.id. A mismatched id doesn't error; it just matches zero events, which looks identical to "no events yet."

Mixing segment- and entity-scope flags

It can seem like more scoping flags always narrow results further. In this case, only one scope can be chosen. --segment-id and --entity-id are mutually exclusive scoping modes with different required companion flags, not composable filters.

Next steps

• Cross-reference audiences activities summary for CRM-style activity (calls, emails) alongside this command's product-detected signal events, for the same segment.
• Resolve a signal's real sig_... id with clay signals get <td_...> before filtering with --signal-ids.

verification:
  status: verified
  tested_at: "2026-09-21"
  product_version: "clay CLI 1.2.0"
  command: "clay audiences signals get --segment-id audseg_0tl84p1ZQ8RRShHSAdX --since 2026-01-01T00:00:00Z --signal-types JobPost,News,CompanyTopicIntent"
  expected_result: "A real (empty, in this workspace) data array and segmentSnapshotAt are returned for segment scope; entity scope returns data only with no segmentSnapshotAt key at all."