particle_alert_create
Create an alert that watches a single entity and sets up recurring email delivery to external recipients whenever it is mentioned on a podcast episode (kind=ENTITY_MENTION) or appears as a speaker (kind=PODCAST_SPEAKER). Pass the entity slug from a resolve tool — resolve a name with particle_entity_resolve, then create the alert with the slug it returns. An alert watches exactly one entity; to cover several entities, call this tool once per entity.
An active alert emails future matches to its configured recipients at the selected delivery cadence until paused or deleted. Only recipients verified for your organization receive alert emails; pending recipients may be saved but stay silent until verified.
When a name has no entity slug, or its entity has no podcast coverage (a startup known by a brand that differs from its legal name, a product, a drug, a code word), create a kind=KEYWORD_MENTION alert with keyword instead of entities. It fires whenever the phrase is spoken — the match particle_podcast_search_transcripts makes for a double-quoted keyword_search phrase (words adjacent and in order), not the looser unquoted match — so also set description to say what the phrase means; that is how same-name mentions of something else are filtered out.
Use the optional filters object to narrow what gets surfaced on every channel (matches list, realtime email, daily/weekly digest). Four independent axes: languages (BCP-47-like tags like ['en','pt-BR'] — empty means all languages), relevance (EVERYTHING returns on-target + incidental matches, RELEVANT narrows to on-target only — dropping passing mentions), source_popularity (ANY keeps every source, POPULAR keeps only matches from podcasts in the top 5% by chart popularity), and speaker_roles (PODCAST_SPEAKER alerts only — REPLACES the default appearance set GUEST/PANELIST/CORRESPONDENT/AUDIENCE/SOUNDBITE_SPEAKER; sending it on an ENTITY_MENTION alert errors with unprocessable_entity).
Billing: creating an active alert can move an eligible organization's subscription from its credit/trial phase to paid fixed-fee billing. Explain this possible billing change and obtain the user's explicit confirmation before creating an active alert. Creating a paused alert (is_active=false) does not trigger this billing transition.
After creation the alert immediately backfills matches from the past week (visible via particle_alert_list_matches) without sending emails for them. To see what an alert would catch BEFORE committing, use particle_alert_preview first. The created alert's id feeds particle_alert_get, particle_alert_update, particle_alert_delete, and particle_alert_list_matches.
Alerts are not covered by zero data retention: the alert's definition and its matched results are stored as part of the alerts feature.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | What signal to watch for. ENTITY_MENTION (default) fires whenever a watched entity is mentioned on a podcast episode. PODCAST_SPEAKER fires only when a watched person is themself an identified speaker (guest/panelist/correspondent/audience). KEYWORD_MENTION fires whenever keyword is spoken — use it when the name has no entity slug (a resolve tool finds nothing, or the right entity has no episodes). Kind is fixed at creation. | |
| title | Yes | Human-readable title for the alert (e.g. 'OpenAI mentions'). | |
| filters | No | Persistent narrowing applied to every surface the alert produces (matches list, realtime email, daily/weekly digest). Omit for no filters — every detected match is surfaced. See AlertFiltersInput for the four axes (languages, relevance, source_popularity, speaker_roles). | |
| keyword | No | KEYWORD_MENTION alerts only (and required for them): the phrase to watch, e.g. Lightfield. Matches like a double-quoted keyword_search phrase — the words adjacent and in order, ignoring case and punctuation, on whole words — in topic-discussion and interview segments, never ad reads, intros, or outros. Also set description to say what the phrase means (e.g. 'Lightfield, the AI-native CRM'); it is how same-name mentions of something else get filtered out. A phrase that matched more than 700 podcast episodes in the past week is rejected as too broad. | |
| entities | No | The entity to watch, as a single slug from the resolve tools (particle_entity_resolve, particle_person_resolve, particle_company_resolve). Person, company, and place/other (knowledge-graph) slugs are all accepted; the resolved type is echoed back in the response. Exactly one for ENTITY_MENTION and PODCAST_SPEAKER — an alert watches a single entity, so create one alert per entity. Omit for KEYWORD_MENTION. | |
| is_active | No | Whether the alert produces matches. Defaults to true. Set false to create it paused. | |
| description | No | Optional longer description of what the alert is for. | |
| notifications | No | Email addresses for recurring alert notifications. Only recipients verified for your organization receive alert emails; pending recipients may be saved but stay silent until verified. At least one recipient must be deliverable. When omitted, defaults to your account email if available; otherwise pass at least one. | |
| output_format | No | Output serialization. 'markdown' (default) returns the LLM-facing rendering. 'json' returns the structured payload as JSON text — use only for programmatic chaining where exact field extraction matters; the JSON shape is larger and noisier for an LLM to read. | |
| delivery_cadence | No | How often matches are emailed: REALTIME (default, one email per match), DAILY (one bundled email each morning), or WEEKLY (one bundled email Monday). |