Alerts
tier:standard

Preview match frequency for an alert before creating it

Kicks off an asynchronous sweep over the past N days (default 7, max 30) and returns a preview_id. Poll GET /v1/alerts/preview/{previewId} until status is completed (or failed). The result includes the total match count, a per-day breakdown, and a small sample of the most-recent matches with full payload so the UI can show "if you create this alert, here's what it would have caught."

post/v1/projects/{projectId}/alerts/preview

Request

  • Base URL: https://api.particle.pro
  • URL: https://api.particle.pro/v1/projects/{projectId}/alerts/preview
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

projectIdstring required

Project ID.

Query parameters

window_daysinteger

Number of days back to sweep. Defaults to 7; capped at 30.

Example:7

Request body

keywordstring

Same as CreateAlertBody.keyword — required for KEYWORD_MENTION, rejected otherwise. A phrase that matched more than 700 podcast episodes in the past week is rejected with 422, as on create.

kind'ENTITY_MENTION' | 'PODCAST_SPEAKER' | 'KEYWORD_MENTION'

Same as CreateAlertBody.kind. Defaults to ENTITY_MENTION.

Response

OK

preview_idstring required

Deterministic preview ID — repeating the same body within the TTL returns the same ID. Poll GET /v1/alerts/preview/{previewId} when status is 'in_progress'.

status'in_progress' | 'completed' required

'in_progress' means a sweep is running (or was just started); 'completed' means an earlier identical preview is still cached and the result is ready to fetch via GET. A 'failed' prior preview is treated as a cache miss and a fresh sweep is started — callers never see 'failed' on this endpoint.

window_daysinteger required

Changes

No recorded changes to this operation across all 2 revisions of this API.