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, salience, 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.
• 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.

​

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.

​

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