> ## 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.

# particle_alert_create

> Create an alert that watches entities and emails you on podcast mentions or speaker appearances.

Create an alert that watches one or more entities and emails you whenever they are **mentioned** on a podcast episode (`kind=ENTITY_MENTION`) or **appear as a speaker** (`kind=PODCAST_SPEAKER`). This is a mutating tool — it creates a real alert in your project.

Watch targets are passed as **entity slugs** from a resolve tool — the same slug→edge contract as the rest of the surface. Resolve a name once with [`particle_entity_resolve`](/mcp/tools/people/entity-resolve), [`particle_person_resolve`](/mcp/tools/people/person-resolve), or [`particle_company_resolve`](/mcp/tools/companies/company-resolve), then create the alert with the slug it returns. The tool resolves each slug to its `(entity_type, entity_id)` internally, so you never handle a raw entity id; the resolved type and name are echoed back in the response.

Every MCP request is scoped to exactly one project by your credential, so the alert is created in **that** project — there is no project parameter. After creation the alert immediately backfills matches from the past 7 days (visible via [`particle_alert_list_matches`](/mcp/tools/alerts/alert-list-matches), flagged `is_backfilled` and never emailed). To see what an alert would catch *before* committing, run [`particle_alert_preview`](/mcp/tools/alerts/alert-preview) first.

<Note>
  Alerts require a plan that includes them (Team, Business, or Enterprise) and an available alert allowance. On a plan without alerts or at the allowance limit, the call returns an `isError` result with upgrade guidance.
</Note>

## Inputs

| Field              | Type             | Required | Default            | Description                                                                                                                                                                                                                                                                        |
| ------------------ | ---------------- | -------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`            | string           | yes      | —                  | Human-readable title (e.g. `"OpenAI mentions"`). Shown in the dashboard and email subject.                                                                                                                                                                                         |
| `entities`         | array of strings | yes      | —                  | Entity slugs to watch, from the resolve tools. Person, company, and place/other (knowledge-graph) slugs are all accepted. At least one is required.                                                                                                                                |
| `kind`             | enum             | no       | `ENTITY_MENTION`   | What to watch for. `ENTITY_MENTION` fires whenever a watched entity is mentioned on an episode; `PODCAST_SPEAKER` fires only when a watched person is themself an identified speaker (guest/panelist/correspondent/audience). Fixed at creation — create a new alert to change it. |
| `delivery_cadence` | enum             | no       | `REALTIME`         | How matches are emailed: `REALTIME` (one email per match), `DAILY` (one bundled email each morning), or `WEEKLY` (one bundled email Monday).                                                                                                                                       |
| `notifications`    | array of strings | no       | your account email | Email addresses to notify. Each must already be verified for your organization (or belong to an org member). When omitted, defaults to your account email if available; otherwise pass at least one.                                                                               |
| `description`      | string           | no       | —                  | Optional longer description of what the alert is for.                                                                                                                                                                                                                              |
| `is_active`        | boolean          | no       | `true`             | Whether the alert produces matches. Set `false` to create it paused (the one-time backfill still runs).                                                                                                                                                                            |
| `filters`          | object           | no       | —                  | Persistent narrowing applied to every surface the alert produces (matches list, realtime email, daily/weekly digest). Omit for no filters — every detected match is surfaced. See [Filter object](#filter-object) below.                                                           |

### Filter object

`filters` is an optional object with up to four independent axes. Omit `filters` (or any individual field) to leave that axis unfiltered. The same shape is accepted on [`particle_alert_update`](/mcp/tools/alerts/alert-update) and is echoed back on every read tool ([`particle_alert_get`](/mcp/tools/alerts/alert-get), [`particle_alert_list`](/mcp/tools/alerts/alert-list)). See [Alerts → Filtering matches](/alerts/overview#filtering-matches) for the wire-level spec.

| Field               | Type                                                                                        | Default                                                         | What it does                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `languages`         | `string[]`                                                                                  | all languages                                                   | Primary language tags the source episode must be in (e.g. `["en", "pt", "zh"]`). A region or script subtag is accepted for readability (`"pt-BR"`, `"zh-Hant"`) but matching is on the **primary tag only** — `"pt-BR"` surfaces every Portuguese episode regardless of region, and `"pt-BR"` + `"pt-PT"` collapse to one. Case-insensitive; echoed back as the canonical primary tag. |
| `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 being discussed, 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 an `unprocessable_entity` error.                                                         |

## Output

A markdown document rendering the created alert's full configuration: the title as an H2, then `**ID:**`, `**Kind:**`, `**Delivery:**`, and `**Status:**` (active/paused) KV rows, an optional `**Description:**` row, a `### Watching (N)` section listing each resolved entity as `Name — type · id`, and a `**Notify:**` row with the recipient emails. When the alert has any active filters, a `### Filters` section follows with one bullet per configured axis (`**Languages:**`, `**Relevance:**`, `**Source popularity:**`, `**Speaker roles:**`).

The `**ID:**` row is the alert id — feed it into [`particle_alert_get`](/mcp/tools/alerts/alert-get), [`particle_alert_update`](/mcp/tools/alerts/alert-update), [`particle_alert_delete`](/mcp/tools/alerts/alert-delete), and [`particle_alert_list_matches`](/mcp/tools/alerts/alert-list-matches).

Sample (`title="OpenAI mentions", entities=["sam-altman"], delivery_cadence="DAILY"`):

```markdown theme={"dark"}
## OpenAI mentions

**ID:** dKxN6Ry2mL9pJ5qW
**Kind:** ENTITY_MENTION
**Delivery:** DAILY
**Status:** active

### Watching (1)

- **Sam Altman:** PERSON · 9rQ2pV…

- **Notify:** you@example.com
```

Passing `output_format: "json"` returns the same fields as compact JSON.

## Example

```text theme={"dark"}
User: Email me whenever Sam Altman is mentioned on a podcast.

Agent calls: particle_person_resolve { "query": "Sam Altman" }
            → reads "- **Slug:**" row → "sam-altman"

Agent calls: particle_alert_create {
  "title": "Sam Altman mentions",
  "entities": ["sam-altman"],
  "kind": "ENTITY_MENTION",
  "delivery_cadence": "DAILY"
}

# Narrow with filters — English-language PODCAST_SPEAKER alert that only fires
# on guest spots on top-5% podcasts (a tight booking signal).
Agent calls: particle_alert_create {
  "title": "Sam Altman — guest spots on top podcasts",
  "entities": ["sam-altman"],
  "kind": "PODCAST_SPEAKER",
  "delivery_cadence": "REALTIME",
  "filters": {
    "languages": ["en"],
    "relevance": "RELEVANT",
    "source_popularity": "POPULAR",
    "speaker_roles": ["GUEST"]
  }
}
```

## Related

* REST equivalent: [`POST /v1/projects/{projectId}/alerts`](/api-reference/alerts/create-an-alert).
* Resolve watch targets first with [`particle_entity_resolve`](/mcp/tools/people/entity-resolve), [`particle_person_resolve`](/mcp/tools/people/person-resolve), or [`particle_company_resolve`](/mcp/tools/companies/company-resolve).
* Size the alert before creating it with [`particle_alert_preview`](/mcp/tools/alerts/alert-preview).
* After creating, see what it caught with [`particle_alert_list_matches`](/mcp/tools/alerts/alert-list-matches), or manage it with [`particle_alert_get`](/mcp/tools/alerts/alert-get), [`particle_alert_update`](/mcp/tools/alerts/alert-update), and [`particle_alert_delete`](/mcp/tools/alerts/alert-delete).