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

> Preview how often an alert would fire before creating it.

Preview how often an alert would fire **before** creating it. Read-only — it creates nothing.

The tool sweeps the past N days (default 7, max 30) for the given entities and returns the total match count, a per-day breakdown, and a small sample of the most recent matches with episode context. Use it to size an alert (pick `REALTIME` vs `DAILY` vs `WEEKLY` cadence based on how chatty the entity is) or to confirm the entity slugs watch the right thing, then call [`particle_alert_create`](/mcp/tools/alerts/alert-create) with the same entities.

Entities are passed as slugs from the resolve tools — [`particle_entity_resolve`](/mcp/tools/people/entity-resolve), [`particle_person_resolve`](/mcp/tools/people/person-resolve), [`particle_company_resolve`](/mcp/tools/companies/company-resolve) — the same input as `particle_alert_create.entities`.

Pass the same `filters` object you intend to save on the alert so the estimate reflects what the alert would actually surface. The filter shape is identical to [`particle_alert_create.filters`](/mcp/tools/alerts/alert-create#filter-object).

<Note>
  The preview runs asynchronously; the tool polls for the result for a few seconds. If the sweep hasn't finished, it returns an in-progress status — call the tool again with the same arguments to read the completed result (the same preview is served from cache, so it is cheap to retry). Changing a filter that affects the count (`languages`, `speaker_roles`) starts a fresh sweep; toggling `relevance` or `source_popularity` returns the same cached count.
</Note>

## Inputs

| Field         | Type             | Required | Default          | Description                                                                                                                                                                                                                                                                             |
| ------------- | ---------------- | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entities`    | array of strings | yes      | —                | Entity slugs to preview (from the resolve tools), same as `particle_alert_create.entities`.                                                                                                                                                                                             |
| `kind`        | enum             | no       | `ENTITY_MENTION` | Signal to preview: `ENTITY_MENTION` or `PODCAST_SPEAKER`.                                                                                                                                                                                                                               |
| `window_days` | integer (1–30)   | no       | 7                | How many days back to sweep.                                                                                                                                                                                                                                                            |
| `filters`     | object           | no       | —                | Persistent narrowing to preview, same shape as [`particle_alert_create.filters`](/mcp/tools/alerts/alert-create#filter-object) (`languages`, `relevance`, `source_popularity`, `speaker_roles`). Only `languages` and `speaker_roles` narrow the historical sweep — see the note below. |

<Note>
  `relevance` and `source_popularity` are graded at read time and don't run on historical episodes, so they do **not** narrow the preview sweep. A preview with `relevance: RELEVANT` returns the same count as one without it — treat the number as an **upper bound** in that case. `languages` and `speaker_roles` do narrow the sweep, so the preview count reflects them exactly. `speaker_roles` is only valid on a `PODCAST_SPEAKER` preview; sending it on an `ENTITY_MENTION` preview returns an `unprocessable_entity` error, matching `particle_alert_create`.
</Note>

## Output

A markdown `## Alert preview` document with `**Window:**` (past N days) and `**Total matches:**` KV rows, a `### By day` section listing each date and its count, and a `### Sample (N most recent)` section showing the most recent matches with episode context. When there are no matches in the window, a closing line notes the alert would not have caught anything.

If the sweep is still running, the output is an in-progress line telling you to call again with the same arguments; on failure, a line suggesting you retry or narrow the entity list.

Sample (`entities=["sam-altman"], window_days=7`):

```markdown theme={"dark"}
## Alert preview

**Window:** past 7 days
**Total matches:** 5

### By day

- **2026-06-12:** 1
- **2026-06-14:** 2
- **2026-06-15:** 2

### Sample (3 most recent)

- The AI Daily (Acme Network) — 3 mentions
  - **Episode:** the-ai-daily-2026-06-15
```

Passing `output_format: "json"` returns `status`, `window_days`, `total_matches`, `by_day`, and `sample` as compact JSON.

## Example

```text theme={"dark"}
User: How noisy would an alert on Sam Altman be?

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

Agent calls: particle_alert_preview { "entities": ["sam-altman"], "window_days": 14 }
            → 5 matches over 7 days → suggest DAILY cadence

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

## Related

* REST equivalent: [`POST /v1/projects/{projectId}/alerts/preview`](/api-reference/alerts/preview-match-frequency-for-an-alert-before-creating-it) plus [`GET /v1/alerts/preview/{previewId}`](/api-reference/alerts/get-the-status-and-result-of-an-alert-preview).
* Resolve the entities to preview 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).
* Once the frequency looks right, create the alert with [`particle_alert_create`](/mcp/tools/alerts/alert-create).