curl -X POST \
-H "X-API-Key: $PARTICLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"entities": [
{
"entity_id": "3CensCwu5G2oKCFgPrNf89",
"entity_type": "COMPANY"
}
]
}' \
"https://api.particle.pro/v1/projects/{projectId}/alerts/preview"{
"preview_id": "<string>",
"status": "in_progress",
"window_days": 123
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}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/ 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.”
curl -X POST \
-H "X-API-Key: $PARTICLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"entities": [
{
"entity_id": "3CensCwu5G2oKCFgPrNf89",
"entity_type": "COMPANY"
}
]
}' \
"https://api.particle.pro/v1/projects/{projectId}/alerts/preview"{
"preview_id": "<string>",
"status": "in_progress",
"window_days": 123
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Authorizations
Pass your API key in the X-API-Key header (recommended).
Path Parameters
Project ID.
Query Parameters
Number of days back to sweep. Defaults to 7; capped at 30.
7
Body
Same as CreateAlertBody.entities — exactly one for entity kinds, omitted for KEYWORD_MENTION.
1 elementShow child attributes
Show child attributes
Same as CreateAlertBody.filters. Pass the filters you intend to save so the estimate reflects what the alert would actually surface. Only languages and speaker_roles narrow the historical sweep; relevance and source_popularity are read-time projections that don't run on historical episodes, so setting them leaves the count unchanged (the estimate is an upper bound when relevance=RELEVANT).
Show child attributes
Show child attributes
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.
100Same as CreateAlertBody.kind. Defaults to ENTITY_MENTION.
ENTITY_MENTION, PODCAST_SPEAKER, KEYWORD_MENTION Response
OK
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'.
'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.
in_progress, completed Was this page helpful?