> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.
# Alerts
> Get notified whenever a person, company, or topic you care about is mentioned — or shows up as a speaker — on a podcast.
export const BillingLink = ({children}) => {
return {children};
};
An alert watches one or more entities — a person, a company, or a knowledge-graph topic — and emails you 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, 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.
## Two kinds of alert
The `kind` is fixed when the alert is created and decides what counts as a match.
| Kind | UI label | Fires when… |
| ----------------- | ------------------ | ------------------------------------------------------------------------ |
| `ENTITY_MENTION` | Any mention | A watched entity is **mentioned** anywhere in an episode's dialogue. |
| `PODCAST_SPEAKER` | Speaker appearance | A watched entity is themselves an **identified speaker** on the episode. |
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.
Mention alerts are the broad net — they fire on any reference, including a passing one. Speaker-appearance alerts are narrow and high-signal — they fire only when the person is actually on the mic. Track the same entity with both kinds (one alert each) when you want to tell "they were talked about" apart from "they showed up."
## How an alert is configured
| Field | What it does |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title` | Human-readable label, shown in the dashboard and email subject. Required. |
| `description` | Optional free-text note describing the alert's purpose (up to 2000 characters). |
| `entities` | One to 100 entities to watch. Each is an `entity_type` (`PERSON`, `COMPANY`, or `KNOWLEDGE_GRAPH_ENTITY`) plus an `entity_id`. |
| `kind` | `ENTITY_MENTION` (default) or `PODCAST_SPEAKER`. Fixed at creation. |
| `notifications` | One to 20 delivery channels. Each delivers to an email address, a [Slack channel](/alerts/slack), or your own [webhook endpoint](/alerts/webhooks) (`EMAIL`, `SLACK`, or `WEBHOOK`). |
| `delivery_cadence` | How matches are batched into emails — see [Delivery frequency](#delivery-frequency). |
| `filters` | Optional narrowing applied before delivery — language, relevance, source popularity, and speaker role. See [Filtering matches](#filtering-matches). |
| `is_active` | Whether the alert matches new episodes. Set `false` to pause without losing history (the one-time creation backfill still runs). |
### 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.
| `delivery_cadence` | UI label | What you get |
| ------------------ | ------------- | --------------------------------------------------------------------------- |
| `REALTIME` | As it happens | A separate email for each match, sent in real time. |
| `DAILY` | Daily digest | One email each morning at 13:00 UTC bundling the past day's matches. |
| `WEEKLY` | Weekly digest | One email each Monday morning (13:00 UTC) bundling the past week's matches. |
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](/alerts/create#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.
| Field | Type | Default | What it does |
| ------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `languages` | `string[]` | `[]` (all languages) | Primary language tags the source episode must be in — a 2–3 letter primary tag, optionally with a region or script subtag for readability (e.g. `["en", "pt", "zh"]` or equivalently `["en-US", "pt-BR", "zh-Hant"]`). Matching is on the **primary tag only**: a `pt-BR` filter surfaces every Portuguese episode regardless of region; `pt-BR` and `pt-PT` collapse to one. Codes are case-insensitive. |
| `relevance` | enum `EVERYTHING` \| `RELEVANT` | `EVERYTHING` | `EVERYTHING` returns both on-target and incidental matches. `RELEVANT` narrows to on-target only — matches where the watched entity is the subject of discussion, dropping passing mentions. |
| `source_popularity` | enum `ANY` \| `POPULAR` | `ANY` | `ANY` keeps every match. `POPULAR` keeps only matches whose source podcast is in the **top 5%** by chart-popularity percentile (multi-region weighted; podcasts not currently charting drop out). |
| `speaker_roles` | `string[]` of `HOST`, `GUEST`, `PANELIST`, `CORRESPONDENT`, `AUDIENCE`, `SOUNDBITE_SPEAKER` | `[GUEST, PANELIST, CORRESPONDENT, AUDIENCE, SOUNDBITE_SPEAKER]` | **`PODCAST_SPEAKER` alerts only.** **Replaces** (not intersects with) the default appearance set. The default excludes `HOST` because hosting the show isn't an appearance — set `["HOST"]` to flip that, or `["GUEST"]` to narrow further. Sending this on an `ENTITY_MENTION` alert returns `422`. |
Start permissive, then narrow. An `ENTITY_MENTION` alert with `relevance: "EVERYTHING"` and no filters surfaces every detected match — useful for sizing. If the email volume is too high, set `relevance: "RELEVANT"` to drop fly-by mentions, or `source_popularity: "POPULAR"` to limit to top-5% shows. For booking work on a `PODCAST_SPEAKER` alert, `speaker_roles: ["GUEST"]` is the tightest signal.
## How alerts flow through the system
```mermaid theme={"dark"}
graph TD
A[Alert] -->|watches| E[Entities]
A -->|delivers to| C[Email channels]
EP[New podcast episode] -->|mention or speaker appearance| M[Match]
A --> M
M -->|realtime or digest| D[Delivery email]
D --> L[Shareable result page]
```
* 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](/alerts/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.
| Method & path | Purpose |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `POST /v1/projects/{projectId}/alerts` | [Create an alert](/alerts/create#3-create-the-alert) |
| `GET /v1/projects/{projectId}/alerts` | List a project's alerts |
| `GET /v1/alerts/{id}` | Get one alert |
| `PATCH /v1/alerts/{id}` | [Update, pause, or resume](/alerts/create#update-pause-and-delete) an alert |
| `DELETE /v1/alerts/{id}` | Delete an alert (soft delete; history retained) |
| `POST /v1/projects/{projectId}/alerts/preview` | [Preview match frequency](/alerts/create#2-preview-match-frequency-optional) before creating |
| `GET /v1/alerts/preview/{previewId}` | Poll a preview's status and result |
| `GET /v1/alerts/{id}/matches` | [List matches](/alerts/results#list-matches) for an alert |
| `GET /v1/alerts/{id}/deliveries` | [List email deliveries](/alerts/results#deliveries) for an alert |
| `GET /v1/alerts/deliveries/{id}` | [Get one delivery](/alerts/results#shareable-result-pages) (shareable landing page) |
| `GET /v1/alerts/matches/{id}` | Get one match (shareable landing page) |
| `GET /v1/alerts/disable?token=…` | Validate an email-footer disable token before confirming (public; token-based) |
| `POST /v1/alerts/disable` | [Disable an alert](/alerts/results#stop-delivery) with an email-footer token (public; token-based) |
## 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`](/errors/plan_does_not_support_alerts) — upgrade from your billing settings.
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`](/errors/add_on_required) until you do. Paused alerts (`is_active: false`) don't count against the allowance.
## Next steps
Resolve an entity, preview how often it would fire, and create the alert — from the API or the dashboard.
Read matches and deliveries, understand the match payload, and share a result page.
Post matches to a Slack channel — connect a workspace and attach a channel.
Deliver matches to your own endpoint as a signed JSON POST, and verify the signature.
Alerts CRUD works with a standard `X-API-Key`, bound to the project the alert belongs to.
Resolve the people, companies, and topics you want an alert to watch.