particle_alert_create

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, particle_person_resolve, or particle_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, flagged is_backfilled and never emailed). To see what an alert would catch before committing, run particle_alert_preview first.

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.

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 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 and is echoed back on every read tool (particle_alert_get, particle_alert_list). See Alerts → 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, particle_alert_update, particle_alert_delete, and particle_alert_list_matches. Sample (title="OpenAI mentions", entities=["sam-altman"], delivery_cadence="DAILY"):

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

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"]
  }
}

REST equivalent: POST /v1/projects/{projectId}/alerts.
Resolve watch targets first with particle_entity_resolve, particle_person_resolve, or particle_company_resolve.
Size the alert before creating it with particle_alert_preview.
After creating, see what it caught with particle_alert_list_matches, or manage it with particle_alert_get, particle_alert_update, and particle_alert_delete.

Get started

Tools

Inputs

Filter object

Output

Example

​Inputs

​Filter object

​Output

​Example

​Related

Inputs

Filter object

Output

Example

Related