> ## 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
> Watch people, companies, and topics across the podcast catalog and get notified by email whenever one is mentioned or appears as a speaker.
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.
| `kind` | Fires when… |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `ENTITY_MENTION` | A watched entity is **mentioned** anywhere in an episode's dialogue. This is the default. |
| `PODCAST_SPEAKER` | A watched entity is themselves an **identified speaker** on the episode. |
A speaker-appearance match fires only when the entity appears as a guest or other speaker on the show, not as its host.
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) to tell "they were talked about" apart from "they showed up."
## How an alert is configured
These are the fields of the JSON body you `POST` to create an alert.
| Field | Required | Type | What it does |
| ------------------ | -------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title` | Yes | string | Human-readable label, shown in the email subject. |
| `entities` | Yes | array (1–100) | Entities to watch. Each is an `entity_type` (`PERSON`, `COMPANY`, or `KNOWLEDGE_GRAPH_ENTITY`) plus an `entity_id`. |
| `notifications` | Yes | array (1–20) | Delivery channels. Each is an `EMAIL` channel (`{ "type": "EMAIL", "email": "…" }`), a `SLACK` channel (`{ "type": "SLACK", "slack_connection_id": "…", "slack_channel_id": "…" }`) — see [Slack](/alerts/slack) — or a `WEBHOOK` channel (`{ "type": "WEBHOOK", "webhook_connection_id": "…" }`) — see [Webhooks](/alerts/webhooks). |
| `kind` | No | enum | `ENTITY_MENTION` (default) or `PODCAST_SPEAKER`. Fixed at creation. |
| `delivery_cadence` | No | enum | How matches are batched into emails — see [Delivery frequency](#delivery-frequency). Defaults to `REALTIME`. |
| `description` | No | string | Free-text note for your own reference. |
| `filters` | No | object | Optional narrowing applied to every surface the alert produces — the matches list, the realtime email, and the daily/weekly digests. Four axes: `languages`, `relevance`, `source_popularity`, `speaker_roles`. On `PATCH`, a supplied `filters` object **replaces** the alert's filter set wholesale; send `{}` to clear. See [Filtering matches](/alerts/overview#filtering-matches) for per-axis behavior and where each axis is enforced. |
| `is_active` | No | boolean | Whether the alert matches new episodes. Defaults to `true`; set `false` to pause without losing history. |
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.
| `delivery_cadence` | What you get |
| ------------------ | -------------------------------------------------------- |
| `REALTIME` | A separate email for each match, sent as it's detected. |
| `DAILY` | One email every day bundling the past day's matches. |
| `WEEKLY` | One email every Monday 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 email — and each configured recipient receives that digest individually.
## 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]
```
* 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`](/api-reference/alerts/list-matches-for-an-alert). 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`](/api-reference/alerts/list-deliveries-for-an-alert).
* 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`](/api-reference/alerts/preview-match-frequency-for-an-alert-before-creating-it) 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}`](/api-reference/alerts/get-the-status-and-result-of-an-alert-preview) 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.
| Method & path | Purpose |
| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [`POST /v1/projects/{projectId}/alerts`](/api-reference/alerts/create-an-alert) | Create an alert |
| [`GET /v1/projects/{projectId}/alerts`](/api-reference/alerts/list-alerts) | List a project's alerts |
| [`GET /v1/alerts/{id}`](/api-reference/alerts/get-an-alert) | Get one alert |
| [`PATCH /v1/alerts/{id}`](/api-reference/alerts/update-an-alert) | Update, pause, or resume an alert |
| [`DELETE /v1/alerts/{id}`](/api-reference/alerts/delete-an-alert) | Delete an alert (soft delete; history retained) |
| [`POST /v1/projects/{projectId}/alerts/preview`](/api-reference/alerts/preview-match-frequency-for-an-alert-before-creating-it) | Preview match frequency before creating |
| [`GET /v1/alerts/preview/{previewId}`](/api-reference/alerts/get-the-status-and-result-of-an-alert-preview) | Poll a preview's status and result |
| [`GET /v1/alerts/{id}/matches`](/api-reference/alerts/list-matches-for-an-alert) | List matches for an alert |
| [`GET /v1/alerts/{id}/deliveries`](/api-reference/alerts/list-deliveries-for-an-alert) | List email deliveries for an alert |
| [`GET /v1/alerts/matches/{id}`](/api-reference/alerts/get-a-single-alert-match) | Get one match |
| [`GET /v1/alerts/deliveries/{id}`](/api-reference/alerts/get-a-single-alert-delivery) | Get one delivery |
| [`GET /v1/alerts/disable`](/api-reference/alerts/preview-alert-disable-action) | Validate an email-footer disable token (public; token-based) |
| [`POST /v1/alerts/disable`](/api-reference/alerts/disable-an-alert-via-email-footer-token) | Disable an alert with an email-footer token (public; token-based) |
## 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](/alerts/slack) covers the full flow, the message format, and how to attach a channel to an alert.
| Method & path | Purpose |
| -------------------------------------------------------------- | ------------------------------------------- |
| `GET /v1/projects/{projectId}/slack/connections` | List a project's connected Slack workspaces |
| `GET /v1/projects/{projectId}/slack/connections/{id}/channels` | List the channels a connection can post to |
| `DELETE /v1/projects/{projectId}/slack/connections/{id}` | Delete a Slack connection (soft delete) |
## 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](/alerts/webhooks) covers the payload shape, signature verification, and retry behavior.
| Method & path | Purpose |
| ----------------------------------------------------------------------- | ------------------------------------------------------------- |
| `POST /v1/projects/{projectId}/webhooks/connections` | Create a webhook connection (returns the signing secret once) |
| `GET /v1/projects/{projectId}/webhooks/connections` | List a project's webhook connections |
| `GET /v1/projects/{projectId}/webhooks/connections/{id}` | Get one webhook connection |
| `POST /v1/projects/{projectId}/webhooks/connections/{id}/secret/rotate` | Rotate a connection's signing secret |
| `DELETE /v1/projects/{projectId}/webhooks/connections/{id}` | Delete a webhook connection (soft delete) |
## 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`](/errors/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`](/errors/add_on_required) until you do. Paused alerts (`is_active: false`) don't count against the allowance.
## Next steps
Resolve an entity, set a delivery channel, and create the alert.
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 uses 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.
ID and slug resolution, cursor pagination, and the error envelope every endpoint follows.