Alerts

An alert watches a single entity — a person, a company, or a knowledge-graph topic — and emails you whenever it is mentioned on a podcast episode, or appears on a show as a speaker. When a name has no entity, such as a startup whose brand differs from its legal name, an alert can watch a keyword instead. To cover several entities, create one alert per entity. Each match links back to the episode, the surrounding dialogue, and an AI-written summary of what was said, so you can read the context without opening the audio.

​

What you can build

• Press monitoring — Get an email the moment a founder, executive, or brand is named on a show, with the transcript excerpt and a summary.
• Competitive intelligence — Track when competitors are discussed across the podcast catalog without polling the API yourself.
• Booking and PR tracking — Use a speaker-appearance alert to learn when a person actually appears as a guest, not just when they’re talked about.
• Topic watch — Follow a knowledge-graph topic and surface every new episode that touches it.
• Brand watch for new names — Use a keyword alert for a brand, product, or code name the entity resolvers don’t know yet.

​

Three kinds of alert

The kind is fixed when the alert is created and decides what counts as a match. A speaker-appearance match is reported only when the entity appears in one of the canonical appearance roles — GUEST, PANELIST, CORRESPONDENT, AUDIENCE, or SOUNDBITE_SPEAKER (raw transcription labels like caller, listener, or reporter are normalized into these buckets). HOST is intentionally excluded: hosting the show isn’t an appearance. A keyword alert matches the way a double-quoted phrase in keyword search does: the phrase’s words adjacent and in order, ignoring case and punctuation, on whole words. It matches only in topic-discussion and interview segments, so ad reads, intros, and outros never fire it. A keyword can collide with an unrelated use of the same word, so set the alert’s description to say what the phrase means — the same relevance check that suppresses entity name collisions uses it to drop mentions of something else. A phrase too broad to alert on — one that matched more than 700 podcast episodes in the past week, such as a common word or a household name like “Trump” — is rejected on create, edit, and preview; use an entity alert for a well-known person or company.

​

How an alert is configured

​

Delivery frequency

delivery_cadence controls how matches turn into emails. Realtime sends one email per match; the two digest cadences accumulate matches as they’re detected and send a single bundled email on schedule. Digest emails are bundled per alert — all of an alert’s matches in the window go into a single digest rather than one email per match, and each configured recipient receives that digest individually (recorded as one shared delivery). Notification emails must be verified before they receive mail. In the dashboard, your own address and your organization’s members’ addresses are verified automatically; API-key callers must use an address that’s already verified for the organization. See Notification emails.

​

Filtering matches

filters is an optional object on every alert that narrows what gets surfaced — it applies identically to every surface the alert produces: the matches list, the realtime email, and the daily and weekly digests. Two axes (relevance, source_popularity) are applied at read/delivery time, so flipping them is fully reversible — tighten and the matches disappear from the list and emails; loosen and they return. The other two (languages, speaker_roles) gate detection itself: they’re also enforced inside the post-create historical backfill and the live matcher, so broadening either axis later won’t surface older matches that were excluded — those rows were never written. Omit filters on create for no narrowing. All four axes default to “no filter”. On PATCH, a supplied filters object replaces the alert’s filter set wholesale (there’s no per-axis merge) — send {} to clear every filter at once, or omit filters from the patch body to leave the existing set unchanged.

​

How alerts flow through the system

• A match is one detected mention or appearance of a watched entity on a single episode. Matches carry the mention count, transcript excerpts, speaker roles, and an AI summary.
• A delivery records one send attempt — a single row covering all of the alert’s recipients, who are each emailed individually. A realtime delivery carries a single match; a daily or weekly digest bundles every match from its window into one delivery.
• Every delivery and match has a shareable landing page that renders the result without the recipient needing an account.

When you create an alert, Particle also runs a one-time backfill over the previous 7 days so the alert isn’t empty on day one. Backfilled matches are real and flagged with is_backfilled: true, but they never trigger an email — only matches detected after creation are delivered. See Alert results.

​

Endpoints

Alerts are managed through the /v1/alerts endpoints. Writes are scoped to a project; reads of a single alert, its matches, and its deliveries are addressed by the resource’s own ID.

​

Data retention

Alerts are not covered by zero data retention. For an organization with zero data retention, an alert’s definition (title, description, keyword, watched entity, filters, and notification addresses) and its results (matches and deliveries) are still stored as part of the alerts feature. See Zero data retention for what the setting covers and how to request it.

​

Plan requirement

Alerts are available on the Team, Business, and Enterprise plans. On a plan that doesn’t include them, creating an alert returns plan_does_not_support_alerts — upgrade from your . Each plan includes a number of active alerts. When you reach the included allowance, buy an Alerts Pack add-on to raise it — further creates return add_on_required until you do. Paused alerts (is_active: false) don’t count against the allowance.

​

Next steps