Alerts

An alert watches one or more entities — a person, a company, or a knowledge-graph topic — and emails the addresses you configure whenever one of them is mentioned on a podcast episode, or appears on a show as a speaker. Each match links back to the episode, the surrounding dialogue, the speaker roles, and — when available — an AI-written summary, so a notification carries the context without a second call. Alerts are created and managed entirely over the REST API. This page covers the model; the request and response schema for each endpoint is generated from the OpenAPI spec and listed in the sidebar under Alerts.

​

What you can build

• Press monitoring — fire when a founder, executive, or brand is named on a show, with the transcript excerpt and a summary in the payload.
• Competitive intelligence — track when competitors are discussed across the catalog without polling the search endpoints 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.

​

Two kinds of alert

The kind is fixed when the alert is created and decides what counts as a match. A speaker-appearance match fires only when the entity appears as a guest or other speaker on the show, not as its host.

​

How an alert is configured

These are the fields of the JSON body you POST to create an alert. Notification emails must be verified for the organization before they receive mail. An API-key caller must supply an address that is already verified for the organization the alert’s project belongs to.

​

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 email — and each configured recipient receives that digest individually.

​

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 windows, speaker roles, a relevance verdict (on_target vs incidental), and, when available, an AI summary (generated asynchronously, so it may be absent on a freshly detected match). Read them with GET /v1/alerts/{id}/matches. The single-match and delivery-landing GETs additionally embed the parent episode — including the podcast’s political bias and its popularity (a percentile plus a Top Podcast / Very Popular / Popular badge) — so a result card renders without a follow-up episode lookup; that episode block is omitted from the paginated matches list.
• A delivery records one send — a single row covering all of the alert’s recipients, who are each emailed individually. A realtime delivery carries one match; a digest bundles every match from its window. Read them with GET /v1/alerts/{id}/deliveries.
• 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, but they never trigger an email.

​

Previewing match frequency

Before committing to an alert, POST /v1/projects/{projectId}/alerts/preview estimates how often a given set of entities and kind would have matched. The preview runs asynchronously: that POST returns a preview_id, then GET /v1/alerts/preview/{previewId} polls for its status and result. Pass the same filters object you intend to save (same shape as on create) so the estimate reflects what the alert would actually surface. Only the axes that gate the historical sweep apply: languages and speaker_roles narrow the count exactly, while relevance and source_popularity are graded at read time and don’t run on historical episodes — so setting them leaves the count unchanged, and the estimate is an upper bound when relevance=RELEVANT. speaker_roles is only valid on a PODCAST_SPEAKER preview (a 422 otherwise, matching create). The preview_id is derived from the count-affecting filters (languages, speaker_roles) too, so changing those starts a fresh sweep, while toggling relevance or source_popularity returns the same cached count.

​

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.

​

Slack delivery

An alert can post matches to a Slack channel. Connecting a workspace is a one-time OAuth install done from the dashboard; the rest is API-driven. The Slack guide covers the full flow, the message format, and how to attach a channel to an alert.

​

Webhook delivery

An alert can deliver matches to your own endpoint as a signed JSON POST instead of, or alongside, email. You configure a webhook connection once per project, then reference it from an alert’s notifications as a WEBHOOK channel. The Webhooks guide covers the payload shape, signature verification, and retry behavior.

​

Plan requirement

Alerts are available on the Team, Business, and Enterprise plans. Organizations on Starter or Growth can’t create alerts and receive plan_does_not_support_alerts until they move to a current plan. 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