Skip to main content
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 with the same entities. Entities are passed as slugs from the resolve tools — particle_entity_resolve, particle_person_resolve, particle_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.
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.

​
Inputs

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.

​
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):
Passing output_format: "json" returns status, window_days, total_matches, by_day, and sample as compact JSON.

​
Example