{"id":103333,"plugin_id":"plugin_asdk_app_6aedf6ea2fac819180910f8b98663c77","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-18T06:19:20.934Z","digest":"41b459c7db58601b215e82db9d84a9969e4da8f2f1f784a409d201b6253e4829","against":null,"payload":{"description":"Clay Signals — watches that detect real-world changes (job changes, new hires, promotions, funding news, job postings, topic intent) and write them as events onto a table or an audience. Use for any request about a workspace's signals: which ones exist, what one watches or writes to, whether one is running, turning one on or off, and why one is or is not producing events.","included_files":[],"name":"signals","skill_md_contents":"---\nname: signals\ndescription: 'Clay Signals — watches that detect real-world changes (job changes, new hires, promotions, funding news, job postings, topic intent) and write them as events onto a table or an audience. Use for any request about a workspace''s signals: which ones exist, what one watches or writes to, whether one is running, turning one on or off, and why one is or is not producing events.'\n---\n\n# Clay Signals\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\nA signal watches a set of records and emits an **event** when something changes\nin the real world — someone changes job, a company posts a role or raises a\nround. It has two halves, and telling them apart is the first thing to get right.\n\n**Resolve the population before discovery.** For a historical question, use the\nrequest and context to distinguish existing workspace records from net-new\nprospects; ask if unclear before exploring either surface. For existing records,\nread the `audiences` skill's `queries.md` and query captured events directly.\nList triggers when managing watches, not as a prerequisite for historical\nqueries. An empty trigger inventory or summary field does not establish that\ncaptured events are absent; check history before proposing a new watch.\n\n| Record             | Id prefix | What it is                                           |\n| ------------------ | --------- | ---------------------------------------------------- |\n| Trigger definition | `td_…`    | The runnable unit: name, run status, filter, output. |\n| Signal             | `sig_…`   | The underlying watch that trigger definitions share. |\n\n**`id` in CLI output is the trigger definition (`td_…`), and it is the only id\nthese commands accept.** `signal.id` is the other record; passing it to\n`clay signals get` is a `not_found`. Everything a user calls \"a signal\" — its\nname, whether it is on, what it writes to — lives on the trigger definition.\n\n**Web intent is out of scope.** Read **Current limitations** at the bottom before telling a\nuser something cannot be done: it lists every gap with what to do instead.\n\n## The commands\n\n```bash\nclay signals list                          # every signal in the workspace\nclay signals get <triggerDefinitionId>     # one signal, with its filter, schedule, and error\nclay signals create --type T --input JSON  # new signal of a supported type\nclay signals update <triggerDefinitionId>  # rename, re-schedule, re-filter, change per-type settings\nclay signals pause <triggerDefinitionId>   # stop signal running, and stop it spending\nclay signals resume <triggerDefinitionId>  # run signal again on its existing schedule\nclay signals delete <triggerDefinitionId>  # remove signal but keeping the events it captured\nclay signals search-topics --query Q --entity-type person|company  # topicIds for a topic intent signal\n```\n\nExcluding web intent makes `list` rows one per signal, so they are safe to count. Narrow\nwith `jq`:\n\n```bash\nclay signals list | jq -r '.data[] | \"\\(.id)  \\(.signal.type)  \\(.runStatus)\"'\nclay signals list | jq '[.data[] | select(.runStatus == \"Errored\") | .id]'\n```\n\nRead `clay signals list --help` and `clay signals get --help` for the exact output\nshapes; they are the contract.\n\n`pause` and `resume` return the signal with `runStatus` already updated, so no\nconfirming call is needed. They write nothing but the status: schedule, filter,\nand destination are untouched, and setting a status a signal already has changes\nnothing, so a retry after a network failure is safe.\n\n**`create`, `update`, `pause`, and `resume` may answer `approval_required`.** Present the\nrequest for the user's decision rather than retrying; approving applies it. A held\ntable-watching `create` has already made its destination table, so rerunning it makes another.\n\n**Only an Active or Paused signal can be toggled.** Any other `runStatus` —\n`Errored`, `Disabled`, `Testing`, `Preview` — is refused.\n\n**Pausing is the credit lever.** A paused signal stops checking and stops\nspending — reach for it when a signal costs more than it is worth, rather than\nsuggesting deletion.\n\n**Reach for `pause` before `delete`.** Pausing already stops the signal running\nand stops it spending, and it is reversible. Nothing undoes a delete: recreating\nthe signal means rebuilding it in the app and starting from a fresh baseline, so\nthe first weeks of coverage are lost again. Confirm with the user before deleting\nsomething they may only want stopped, and show them `get` output first.\n\n**Identify a write target by id, not by name.** `get` returns `input` — the same\ntargeting the list row carries — so read the signal back and check what it\nactually watches before pausing or deleting it. Names are not unique and are not\nreliable selectors; see the `ALL` warning under **Signals on audiences** for the\nspecific way name-matching goes wrong on audience signals.\n\n**Deleting keeps the data.** The destination table and its rows survive, as do\nthe signal activities already on audience entities — a delete removes the watch,\nnot the history. It is also **not** idempotent: a second delete of the same id\nreturns `not_found`, which here means \"already gone or never existed\", so do not\nread it as confirmation.\n\n## Creating and updating a signal\n\n**`clay signals create --help` is the list of creatable types and the authority on each\none's `--input` shape.** It is generated from the supported set, so it is never out of date;\nanything absent from it is an app job, and passing such a type says so by name rather than\nfailing obscurely. The same goes for `clay signals update --help` and what that type lets you\nchange.\n\nTypes differ in what they take. The watch — a table view, or audience segments — is common to\nall of them, but the settings beside it are not: one type takes search filters, another a set\nof topic providers. Never carry an `--input` shape from one type to another; read the shape\nfor the type in hand, and prefer copying a working signal of that same type:\n\n```bash\nclay signals get td_abc123 | jq '.signal.inputs'   # copy this, edit it, feed it back\n```\n\n**Never guess a vocabulary value — fetch it.** Several `--input` fields take a fixed set of\nexactly-spelled values that a misspelling silently turns into \"matches nothing\": news\n`topics`, job-post `seniority` and `employment_type`, new-hire seniority levels and company\nsize/revenue buckets. Those closed sets are enumerated in full in `clay signals create --help`,\nunder each type's `--input` shape — read the values there rather than recalling them. The two\nvocabularies that page cannot enumerate: topic intent `topicIds`, which\n`clay signals search-topics` resolves (see **Topic intent types** below), and new-hire\n`job_functions`, which is resolved per workspace — prefer `job_title_keywords` over it.\n\n**Check for a duplicate first.** Nothing stops two signals of the same type watching the same\nrecords, and each is charged in full. `clay signals list` and compare `signal.type` against\n`input` before creating another.\n\n**Resolve audience ids, never names.** `--input`'s `segmentIds` are ids from\n`clay audiences list --entity-type companies|people`. See the `ALL` warning under **Signals on\naudiences** — matching words in a segment name is how the wrong signal gets written.\n\n**A table-watching signal needs three ids, and only two have a command.** `clay tables list`\ngives `tableId`, `clay tables columns list <tableId>` gives the `fieldId` for the identifier\nfield. There is no command for `viewId` — read it off the table's URL in the app, or off\n`input.table.viewId` of an existing signal on the same table:\n\n```bash\nclay signals list | jq -r '.data[] | select(.input.table.id == \"t_abc123\") | .input.table.viewId'\n```\n\n**A created signal is Paused.** It neither runs nor spends until `clay signals resume <id>`.\nThat order is deliberate: read it back, confirm `input` is what you meant, then resume. Pass\n`--activate` only when the watched set and its identifier coverage have already been checked,\nbecause a check that has run cannot be taken back.\n\n**Price the signal before choosing a cadence.** Which of the two billing models a type uses\ndecides whether cadence matters at all — see **Two billing models** under **Common issues**.\nFor a per-record-checked type, cadence multiplies the bill and a large watched view on a fast\ncadence is among the most expensive things a workspace can run; narrow the watched view before\nslowing the cadence. Omitted, `--schedule` takes that type's own default, which is not the\nsame across types — and some types accept only a subset of the cadences (topic intent checks\nweekly at the fastest, matching how often its providers refresh); the `--type` values in\n`create --help` list each type's set.\n\n**Some types are created with a default filter.** Omitting `--filter` takes it, matching the\napp — job change and promotion start at `confidence >= 90`, which is why a new signal can look\nhealthy and still emit less than expected. Passing `--filter` replaces the default rather than\nadding to it.\n\n**`--filter` and a type's own `filters` are two different things, and confusing them is the\nmain way a signal ends up watching for the wrong thing.**\n\n- **`--filter`** decides which _detected_ events fire. One flag, the same on every type, and\n  what `get` returns as `filter`.\n- **`filters`**, a key inside `--input` on the types that have one, is the search that decides\n  what the signal looks for in the first place — which hires count for a new-hire signal,\n  which postings for a job-post signal, which articles for a news signal. It lives in\n  `signal.inputs.filters`.\n\nA search `filters` document replaces rather than merges, and the search schemas are large and\nheavily defaulted: a key you leave out is set back to its default, not left as it was. So edit\na real one rather than composing one from memory:\n\n```bash\nclay signals get td_abc123 | jq '.signal.inputs.filters'   # copy this, edit it, feed it back\n```\n\n**Topic intent types have their own gate and their own vocabulary trap.** `PersonTopicIntent`\nand `CompanyTopicIntent` are gated separately from the rest of signals, so `create` can fail\nwith exit 3 on a workspace where every other type works. Their setting is `providerConfigs` —\nwhich intent providers to ask, and which of each provider's topics to watch — and its\n`topicIds` come from each provider's own catalog (opaque ids, except bombora's, which are the\ntopic names spelled exactly).\n\n**Resolve `topicIds` with `clay signals search-topics` — never guess them, and never copy them\noff another signal.** A guessed id validates and then matches nothing, and another signal's\nids encode _its_ topics, not the ones this user asked for. Describe what the user wants to\ndetect in plain language and take the ids from the result, per provider:\n\n```bash\nclay signals search-topics --query 'sales intelligence tools' --entity-type company\n```\n\nEach result maps one topic to its id in every provider's catalog (`matches.<provider>[].id`);\nuse each id only in a `providerConfigs` entry for that same provider. Pass the entity type\nmatching the signal type — a `person` search excludes person-restricted topics and returns no\nbombora ids, because bombora is company-only.\n\nA provider config without `topicIds` watches every topic that provider tracks, not none — and\nevery topic is charged per record on every run, so an omitted topic list is a cost decision,\nnot a blank.\n\nWhich providers a topic intent signal uses is also fixed at creation, unlike its topics:\n`update` can change the `topicIds` and `tiers` inside each config, but adding or dropping a\nprovider is refused because each one keeps its own detection baseline. Choose the provider set\ndeliberately at create time — changing it later means a new signal.\n\n**A failed table-watching create leaves something behind, and recovery depends on where it failed.**\nThe destination is set up before the signal is validated, and nothing cleans either up.\nRead the error to tell the two apart before retrying:\n\n- **The signal was rejected** — an unknown view, a watched view over the monitoring limit, a\n  rejected filter, missing permissions. No signal exists, so `clay signals list` shows nothing:\n  it lists signals, not tables. Retrying makes a _second destination_, not a second signal.\n  Find the leftover table first. Without `--destination-table` that is a new table named\n  `<Type> Events from <watched table> (<date>)`, which `clay tables list` will show; with\n  `--destination-table` the table you named is now carrying a source that feeds nothing. Remove\n  either in the app.\n- **The signal was created but the command still failed**, on reading it back. The signal\n  exists and runs while the command exits non-zero, so here `clay signals list` does show it —\n  check there before retrying, or you end up with two signals.\n\nAn audiences signal is created in a single step and has no destination table, so neither case\napplies to one.\n\n**What a signal watches is fixed once created.** No type lets `update` repoint a watched\ntable, view, or identifier field — create a new signal and delete the old one. Name, schedule,\nand filter are always editable; beyond those, what `update` accepts is per type and narrower\nthan what `create` took, so check `clay signals update --help` rather than assuming a field\nthat was settable at creation still is. Run status is on neither verb; `pause` and `resume`\nown it.\n\n**`update --input` changes only the keys it names, and replaces each of them whole.** Keys it\nleaves out are untouched, so an update changing `segmentIds` does not disturb `filters` and\nvice versa. `segmentIds` is the one key that requires an audiences signal — a table-based one\ncannot be given audiences to watch.\n\nWithin one key there is no merging, though: a `filters` document replaces the saved search\noutright, and any key absent from the one you send goes back to its default rather than\nkeeping its current value. Read the current search, edit it, send it back whole.\n\n**Replacing a filter is how a signal quietly starts or stops emitting.** `update --filter`\nreplaces outright rather than merging, and `--clear-filter` removes it. Read the current one\nfirst:\n\n```bash\nclay signals get td_abc123 | jq .filter\n```\n\n**A missing or stale identifier silently drops a record.** Nothing reports it, so check\ncoverage on the watched view or segments before trusting a new signal — see **The watch\ncolumn is a prerequisite** under **Signal types**.\n\n## input is not destinationTable\n\nThe single most common misreading of this output. They are separate axes, and on\na table-based signal they are **two different tables**.\n\n- **`input`** — what the signal watches. Either `input.table` (`{ id, viewId }`)\n  or `input.audiences` (`{ segmentIds, entityType }`); at most one is set, and\n  both are null for a custom signal, which is driven by an action instead.\n- **`destinationTable`** — where its events are written.\n\n`destinationTable` is null for an audiences-based signal, because its output goes\nback onto the audience entities rather than into a table. It is also null when a\ntable-based signal has no destination resolved, so `destinationTable: null` alone\ndoes not prove a signal is audience-based — check `input`.\n\n## Signals on audiences\n\nAn audiences-based signal writes its output back to the audience entities as\n**signal activities**. Nothing appears in a table, so don't go looking for one.\n\n**Where the user sees it in the app.** An audiences-based signal is listed only\nunder **Companies** (`ACCOUNT`) or **People** (`CONTACT`) → **Data hub** →\n**Signals**. It never appears on the **Signals** page in the main sidebar, which\nlists table-watching signals only. When a user asks where to find, check, or edit\nan audiences-based signal, send them to Data hub for its entity type. If they are\non the Signals page and can't find it there, that is expected and does not mean\nthe signal is missing. A table-watching signal is the reverse: it appears on the\nSignals page and not in Data hub.\n\nIts `input.audiences.segmentIds` are audience ids from `clay audiences list`, and\n`entityType` uses the middle spelling — `ACCOUNT` / `CONTACT`, not\n`companies` / `people`.\n\n**`ALL` in `segmentIds` is a sentinel, and it collides with real segment names.**\nIt means the whole audience of that entity type — not a saved segment, and not a\nsegment called \"BigQuery ALL\" for example. A signal watching everything\nand a signal watching a segment whose name contains \"ALL\" are indistinguishable\nto a text match, so **never pick a signal by matching words in a name**: resolve\nsegment ids with `clay audiences list` and compare `segmentIds` against those\nids. This matters most before a write — `delete` on the wrong match is not\nrecoverable.\n\nSee the `audiences` skill's `filters.md` for selecting records **by** their\nsignal events — \"companies with a job posting in the last 30 days\" is an\naudience filter, not a signals command.\n\nTo read the captured events for one person or company, use the Audiences\n`signals list` command with `--entity-id`. For a saved segment, use `signals list`\nwith `--segment-id`; to aggregate that segment by signal id and type, use\n`signals summary`. These are separate from `clay signals`, which manages the\nsignal definitions and run status. The segment commands accept `--signal-ids`\nas underlying `sig_…` ids, not trigger definition `td_…` ids.\n\n## A signal that runs but produces nothing\n\nWork down this list — the first two explain most cases, and both are visible\nwithout spending anything.\n\n1. **`runStatus`.** Only `Active` and `Preview` run. `Testing`, `Paused`, and\n   `Disabled` do not; `Errored` stopped after a failure.\n2. **`filter`, from `get`.** Job change and promotion signals are created with a\n   default of `confidence >= 90`, so a signal can run correctly and still emit\n   far fewer events than the user expects. A `null` filter is unfiltered; a\n   missing filter is not the same as no filter having been configured.\n3. **`error`, from `get`.** Populated when `runStatus` is `Errored`.\n   `userFriendlyMessage` is what the app shows; `message` is the underlying\n   failure.\n4. **`schedule`, from `get`.** Cadences are often weekly or monthly, so a signal\n   may simply not have run yet. `schedule.lastRunAt` and the top-level\n   `lastRunAt` are the truth — `list` deliberately omits them.\n5. **Where the output goes.** An audiences-based signal writes activities onto\n   entities, not rows into a table (see above).\n\n## Signal types\n\n| `signal.type`            | Fires when                                                  | Watches by                        |\n| ------------------------ | ----------------------------------------------------------- | --------------------------------- |\n| `JobChange`              | A tracked person's current company changes                  | Person LinkedIn URL               |\n| `NewHire`                | A tracked company hires someone matching your criteria      | Company identifier                |\n| `Promotion`              | A tracked person's title advances at their current company  | Person LinkedIn URL               |\n| `JobPost`                | A tracked company opens a job posting matching your filters | Company identifier                |\n| `News`                   | A tracked company appears in news, including funding rounds | Company identifier                |\n| `LinkedinPostMentions`   | Discontinued — a post mentioned your organization           | Organization id + connection      |\n| `PersonTopicIntent`      | A tracked person researches one of your topics              | Person LinkedIn URL               |\n| `CompanyTopicIntent`     | A tracked company researches one of your topics             | Company identifier                |\n| `Custom`                 | An enrichment you configure returns a change                | Any action output                 |\n| `WebsiteVisitorTracking` | A de-anonymized visit hits your website (web intent)        | Tracking script, not a record set |\n| `FakeSignal`             | Internal test type — not created through product flows      | —                                 |\n\n`LinkedinPostMentions` is no longer available: never suggest it, and do not try to create or\nupdate one — both are refused. A workspace may still hold signals of the type from before,\nand those are fine: they appear in `list` and can be read, paused, resumed, and deleted like\nany other. For an existing one, know that it watches an organization rather than a record\nset — an `organizationId` and a LinkedIn connection, with an optional table or audience\nfiltering only _who_ mentioned you — so check those three when its coverage looks wrong.\n\n**The watch column is a prerequisite, not a detail.** A person-based signal tracks the\nLinkedIn URL on each record; a record with a missing, stale, or invalid URL is silently\nnot monitored, and no error tells you so. Check coverage before trusting a signal — but\ncheck it in the store the signal actually watches, which `input` on `get` tells you:\n\n- **`input.audiences` set** — the records live in Audiences, so\n  `clay audiences records search-count` with a `NotEmpty` filter on the identifier\n  field gives the fill rate, per the `audiences` skill.\n- **`input.table` set** — the records live in that table, and `input.table.viewId`\n  narrows the watch to one view when it is set, so coverage has to be measured over that\n  view and not the whole table. Read `/tables-cli`.\n\n`signal.inputs` on `get` is the stored per-type configuration, returned as-is — read a\nworking signal of a type before assuming its shape.\n\nA user rarely names a signal type; they describe an outcome. The sections below are the\nprompt shapes that map to each type — recognize one, then follow **Matching a request to a signal**\nbelow rather than jumping straight to `create`.\n\n### `JobChange`\n\nUse when the request is about tracked _people_ changing employers: \"tell me when any of my\nchampions change jobs\", \"which of my past customers landed somewhere new\", \"alert me when a\ncontact leaves their company\", \"track job changes across my CRM contacts\". The employer is\nwhat changes — a new title at the same company is `Promotion`, and \"who did this _account_\nhire\" is `NewHire`.\n\n### `NewHire`\n\nUse when the request is about tracked _companies_ bringing people on: \"tell me when a target\naccount hires a VP of Sales\", \"which accounts just brought on a new CMO\", \"alert me when a\ncompany on this list hires into the persona I sell to\", \"find new decision-makers at my\naccounts\". Fires when someone has actually joined; a role that is merely open is `JobPost`.\n\n### `Promotion`\n\nUse for title advancement at the same company: \"tell me when my champion gets promoted\",\n\"track title changes in my buying committee\", \"who in my contacts moved up to director or\nabove\", \"congratulate contacts on new roles\". If the company changed too, that is\n`JobChange`.\n\n### `JobPost`\n\nUse for hiring as a buying trigger, while the role is open: \"which of my accounts are hiring\nSDRs\", \"alert me when a target account posts a job mentioning Kubernetes\", \"companies hiring\nfor the role my product serves\", \"use open roles to prioritize outreach\".\n\n### `News`\n\nUse for company news and fundraising: \"tell me when my accounts raise a round\", \"track\nacquisitions in my territory\", \"alert me when a customer launches a product or hits the\nnews\", \"use funding events to trigger outreach\". Fundraising is a `News` topic, not a\nseparate type.\n\n### `LinkedinPostMentions`\n\nRecognize \"tell me when someone mentions our company on LinkedIn\", \"track posts talking\nabout our product\", \"who is talking about us\" as brand-mention asks — and then do **not**\nreach for this type: it is no longer available (see the note above). Never suggest it, and\nnever try to create or update one. If the workspace already has one, reading and managing it\nis fine; for a _new_ brand-mention request, say plainly that no signal covers it anymore.\n\n### `PersonTopicIntent`\n\nUse when the request is about which tracked _people_ are researching something: \"which of my\ncontacts are researching data warehouses\", \"people in-market for our category\", \"prospects\nshowing intent on the problem we solve\", \"who is actively looking into this space right now\".\n\n### `CompanyTopicIntent`\n\nUse when the request is about which tracked _accounts_ are researching or in-market:\n\"I want to know which of my accounts are researching or in-market for <something>\",\n\"surface accounts showing buying intent for our category\", \"which target accounts are\nin-market right now\", \"pull third-party intent on my account list\", \"prioritize accounts\nspiking on <topic>\". Account-level intent; the same ask about named individuals is\n`PersonTopicIntent`.\n\n### `Custom`\n\nRecognize \"fire when <some enrichment or action output> changes\" with no built-in type\ncovering it as a `Custom` signal — a change watch over an arbitrary action's output. It\ncannot be created or updated from these commands: building or changing one is an app job,\nso route the user there. Existing ones read and manage normally.\n\n### `WebsiteVisitorTracking`\n\nRecognize \"who visited my website\", \"de-anonymize our site traffic\", \"alert me when a target\naccount hits our pricing page\" as web intent — a real signal type, but out of scope for\nthese commands entirely: it cannot be created, updated, or even read here (see **Current\nlimitations**). Route the user to the Clay app.\n\n## Matching a request to a signal\n\nWhen a prompt matches one of the shapes above, work in this order — the answer is usually an\nexisting signal's output, not a new signal:\n\n1. **Look at what already exists.** `clay signals list`, and compare `signal.type` and\n   `input` against what the user is asking about — resolve tables and segments by id, never\n   by name (see **Signals on audiences**). A signal of the right type watching the right\n   records already answers the question, and a second one would double the spend.\n2. **If a fitting signal exists, read its output rather than creating another.**\n   For a table-based signal, read `destinationTable.id` with the `/tables-cli` skill. For an\n   audiences-based signal, use `clay audiences signals list --entity-id` when\n   one person or company is in scope, `clay audiences signals list --segment-id`\n   for full event payloads across a saved segment, or `signals summary` for\n   counts within a saved segment. The segment commands can filter\n   with the underlying `signal.id` (`sig_…`) when the user means one particular\n   signal.\n3. **If none fits, ask before creating.** Do not create a signal the user did not ask for —\n   propose it and get a yes. Before the create, show them exactly what will exist so they\n   can confirm: the type, what it will watch (table + view + identifier field, or audience\n   segments by id and name), the per-type settings (`filters`, `providerConfigs`, topics),\n   the schedule, the event filter, and how it is charged (see **Two billing models**). Note\n   that it is created Paused and only starts checking — and spending — on\n   `clay signals resume`.\n\n## How signals get used\n\n**Resolve workflow trigger intent from context.**\nThe workflow CLI supports `audience_signal`, bound to the underlying `signal.id`,\nwhen signal events are the intended trigger. Compare plausible sources using the\nrequest and prior discussion, then ask if the choice remains ambiguous. See\n`workflows/trigger-selection.md` for examples and binding details.\n\nThe standard GTM shape is **detect → qualify → act**, and a signal is only the\nfirst step. When helping a user design one, ask what the other two are.\n\n- **Champion tracking** — a `JobChange` signal on an audience of customer\n  contacts (champions). An event means a warm relationship just landed at a new\n  account: the play is enrich the new company, check ICP fit, alert the owner or\n  open a CRM opportunity. The qualification step matters — a board seat or\n  advisory role added alongside an existing job is not a \"champion moved\".\n- **Signal-based plays on audiences** — the app pairs a signal with a segment\n  whose filter selects records with recent events of that type (the\n  `signal_events` filter — see the `audiences` skill's `filters.md`). The\n  segment is live: records enter as events arrive and age out with the lookback\n  window. Use that segment for membership-based workflows or exports; use an\n  `audience_signal` workflow trigger when the user wants to react to signal events.\n- **Hiring / funding as account intent** — `JobPost` and `News` on a company\n  audience, feeding prioritization: a company hiring for the role your product\n  serves, or one that just raised, moves up the outreach queue.\n- **Topic intent** — `PersonTopicIntent` / `CompanyTopicIntent` mark who is\n  researching your category now; usually combined with fit filters rather than\n  acted on alone.\n\nEvents land in the destination — table rows, or activities on audience entities.\nWorkflows can react through an `audience_signal` trigger or use a segment when\nmembership is the intended condition.\n\n## Common issues and how to avoid them\n\nBeyond the checklist above, these are the recurring ways signals surprise\nusers in practice:\n\n- **Signals detect changes after monitoring starts.** A change-detection signal\n  (job change, promotion) diffs fresh data against a baseline captured when\n  monitoring began. Changes that happened before the signal existed produce no\n  events, except for the one-time historical lookback at setup (job change\n  defaults to 3 months, `lookBackTimeWindowInMonths` in `signal.inputs`). Set\n  expectations accordingly: a signal created today mostly pays off in the\n  following weeks, and \"this person changed jobs last quarter, why no event?\"\n  is usually this, not a bug.\n- **Two billing models, and only one scales with records watched.** Check which\n  before estimating anything.\n  - **Per record checked** — `JobChange`, `NewHire`, `Promotion`, `JobPost`,\n    `PersonTopicIntent`, `CompanyTopicIntent`. These charge for every record examined on\n    every run whether or not it produces an event, so a large watched set at a fast\n    cadence is one of the most expensive things a workspace can run. Size it as\n    (records in the watched view or segments) × runs per month, and prefer narrowing the\n    watched set over slowing the cadence. The two intent types multiply that by each\n    selected provider's selected topics (`providerConfigs` in `signal.inputs`), so a\n    quiet audience still pays in full and adding a topic is a cost change.\n  - **Per result** — `News`, `Custom`, `LinkedinPostMentions`. These charge for events\n    emitted, not records scanned, so the record × frequency formula does not apply and\n    can be wildly wrong in either direction: a large quiet audience costs little, while a\n    small noisy one can cost a lot. Estimate from expected event volume, and treat a\n    loosened event filter as a cost change rather than only a coverage change.\n- **A signal that exhausts its credit limit stays stopped.** An audience signal can\n  carry a `creditLimit`, and exhausting it does not throttle the signal — the run sets\n  its status to `Paused`, and nothing puts it back. The one automatic credit-cycle\n  reactivation in the product is specific to web intent, so an ordinary audience signal\n  stays paused until someone starts it again. Do not tell a user it will pick up next\n  cycle: check `runStatus` on the signals they expect to be running, and once the limit\n  is raised or the cycle rolls over, `clay signals resume` each paused one. Insufficient\n  credits surfaces the same way — at run time, not as a validation error at setup.\n- **The default filter eats events silently** — `confidence >= 90` on job\n  change and promotion (see the checklist). When a user reports \"missing\"\n  events for changes that really happened, check the filter before the watch.\n- **Restrictive filters look like a broken signal, and there are two layers of\n  them.** The search in `signal.inputs.filters` — news topics, job title\n  keywords, seniority, locations — decides what the signal looks for, and the\n  `filter` from `get` decides which of what it found actually fires. A signal\n  can be healthy and emit nothing because either layer excludes everything, so\n  read both before concluding events are missing, and loosen one at a time so\n  you can tell which was responsible.\n- **Watching a live segment means the watch list moves.** An audience-based\n  signal monitors current segment membership, so records entering the segment\n  start being monitored (with a fresh baseline — see above) and records\n  leaving stop. If a user needs a stable cohort watched, the segment filter\n  needs to define one.\n- **Duplicate signals double the spend.** Two trigger definitions can share a\n  watch or overlap on the same records. Before creating a signal, run\n  `clay signals list` and check for an existing one of the same type over the\n  same input — and prefer pausing or deleting the redundant one over leaving\n  both running.\n\n## Error codes\n\nJSON on stdout, a typed error envelope on stderr. Exit codes: `0` ok, `2`\nvalidation, `3` auth, `4` rate-limit, `5` network, `6` not-found.\n\n- `3` usually means signals are not enabled for the workspace, or the credential\n  cannot read them — a workspace-config answer for the user, not a retry.\n- `6` on `get` most often means a `sig_…` was passed where a `td_…` belongs.\n\n## Current limitations\n\nEverything below is **not yet**, not impossible. This section shrinks as\ncommands land — when one does, delete its entry rather than rewording it, and\ncheck whether the caveats elsewhere in this file still hold.\n\n- **Not every type can be created yet.** `clay signals create --help` lists the ones that\n  can; `Custom` and web intent are app-only for now, and `create` refuses them by name. This\n  set grows, so read the help rather than a remembered list. `LinkedinPostMentions` is no longer available — see **Signal types**.\n- **`update` is narrower than `create`, per type.** Name, schedule, and filter are always\n  editable; everything else depends on the type, and a watched table, view, or identifier\n  field is fixed for all of them.\n- **Web intent (`WebsiteVisitorTracking`) is out of scope entirely.** `list` excludes it\n  and every other command refuses it, so these commands never report on or change one at\n  all — a web intent question is an app question.\n- **`list` cannot filter or paginate.** It returns every signal in one\n  response; narrow with `jq`. There is no server-side filter by type, status,\n  or input.\n- **`list` omits the schedule, last run, filter, and error.** The route behind\n  it does not carry them, so they come from `get` one signal at a time — an\n  N+1 for questions like \"which signals are stale?\"\n- **No cost, health, or test commands.** The API exposes estimated signal cost,\n  job status, and validation info, but nothing surfaces them yet: size a signal\n  by hand (see **Common issues**), and diagnose from `get`'s `runStatus`,\n  `error`, and `schedule`.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}