Skip to main content
An alert produces two kinds of record. A match is one detected mention or appearance of a watched entity on a single episode. A delivery records one send attempt — a single row covering all of the alert’s recipients, who are each emailed individually. A realtime delivery carries a single match; a daily or weekly digest bundles every match in its window into one delivery.

​
Matches

Each match links a watched entity to the episode it was found on, with the evidence that triggered it.
FieldDescription
entity_type, entity_idThe watched entity this match is for.
source_type, source_idThe source object. Currently always a podcast episode.
detected_atWhen the match was produced. For backfilled matches this is the episode’s publish time.
mention_countMentions in the episode (ENTITY_MENTION), or spoken lines by the entity (PODCAST_SPEAKER).
salienceHow central the entity is to the episode, 0–1.
mention_variantsThe surface forms the entity was referred to by. ENTITY_MENTION only.
rolesCanonical speaker roles the entity appeared as — GUEST, PANELIST, CORRESPONDENT, or AUDIENCE. PODCAST_SPEAKER only.
windowsTranscript excerpts: contiguous dialogue around each mention, with per-line speaker, timestamps, and an is_mention flag.
llm_summaryAn AI-written summary of the match with context from the entity’s mentions over the prior 7 days. Generated shortly after the match; absent until then, and permanently absent if generation fails after retries (treat a missing summary the same either way).
is_backfilledtrue for matches found by the post-create historical sweep. These never sent an email.
episodeEpisode and podcast metadata (titles, image, slugs) so a result renders as a card without a second lookup. Present on the single-match and delivery-detail responses and on preview samples; omitted from the paginated matches list below — fetch a single match (or GET /v1/podcasts/episodes/{id}) when you need it there.

​
List matches

curl "https://api.particle.pro/v1/alerts/8Qw2mRk7Tf9LpZ/matches?limit=20" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Results are newest-first and paginated with the standard cursor envelope. Narrow to a window with after and before — both exclusive bounds on detected_at. A bare date is parsed as midnight UTC, so to include a whole day set before to the next day (the call below captures all of June 1 through June 9): 
curl --get "https://api.particle.pro/v1/alerts/8Qw2mRk7Tf9LpZ/matches" \
  --data-urlencode "after=2026-06-01" \
  --data-urlencode "before=2026-06-10" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "id": "Mt7k…",
      "alert_id": "8Qw2mRk7Tf9LpZ",
      "kind": "ENTITY_MENTION",
      "entity_type": "COMPANY",
      "entity_id": "3CensCwu5G2oKCFgPrNf89",
      "source_type": "PODCAST_EPISODE",
      "source_id": "78cgekLUjCJBUZbj3s5K8Y",
      "detected_at": "2026-06-08T11:02:00Z",
      "mention_count": 4,
      "salience": 0.21,
      "mention_variants": ["Nvidia", "NVDA"],
      "llm_summary": "Discussed Nvidia's data-center revenue in the context of …",
      "deliveries": [
        { "id": "Dl9…", "channel": "EMAIL", "status": "SENT", "sent_at": "2026-06-08T11:03:12Z" }
      ]
    }
  ],
  "has_more": true,
  "cursor": "…"
}
The match payload differs by alert kind. ENTITY_MENTION matches carry mention_count, mention_variants, and the mention windows. PODCAST_SPEAKER matches carry roles and report the entity’s spoken-line count in mention_count. windows are present on both when the match is hydrated (the single-match and detailed delivery views below).

​
Backfill

When an alert is created, Particle sweeps the previous 7 days and writes any matches the live pipeline would have produced, so the alert isn’t empty on day one. These are flagged is_backfilled: true with detected_at set to the episode’s publish time, and they never trigger an email — only matches detected after creation are delivered.

​
Deliveries

The deliveries log is the email audit trail for an alert — one row per send attempt. 
curl "https://api.particle.pro/v1/alerts/8Qw2mRk7Tf9LpZ/deliveries?limit=20" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "id": "Dl9…",
      "alert_id": "8Qw2mRk7Tf9LpZ",
      "channel": "EMAIL",
      "status": "SENT",
      "sent_at": "2026-06-08T11:03:12Z",
      "match_count": 1,
      "created_at": "2026-06-08T11:03:10Z",
      "matches": [
        { "id": "Mt7k…", "entity_type": "COMPANY", "detected_at": "2026-06-08T11:02:00Z" }
      ]
    }
  ],
  "has_more": false
}
status is one of SENT, FAILED, or SKIPPED, and error_message carries the detail for anything that isn’t a clean success — so check it even when status is SENT:
  • SENT — the email was sent. If some recipients failed on a digest, the status stays SENT (so those who got it aren’t re-emailed) and error_message records the partial failure, e.g. 2/5 recipients failed.
  • FAILED — no recipient received the email; error_message has the reason, and the send is retried.
  • SKIPPED — no email was attempted (for example, the alert has no email recipients); error_message explains why.
A realtime delivery has match_count: 1; a daily or weekly digest groups its whole window into one delivery with a higher match_count. Each delivery embeds a lightweight summary of the matches it included — for the full transcript excerpts, fetch the delivery’s shareable page or the individual matches.
Alert detail page showing the watched entity, trigger, recipient, frequency, and a deliveries table

​
Shareable result pages

Two API endpoints return a single result on its own — fetch one delivery or match by ID, without the parent alert:
  • GET /v1/alerts/deliveries/{id} — one delivery and the matches it contained
  • GET /v1/alerts/matches/{id} — one match, fully hydrated
These JSON endpoints (on api.particle.pro) also back the human-readable landing pages the platform renders for the View in browser and per-result links in alert emails — those email links point at platform.particle.pro, not the API. 
# A delivery landing page, with full transcript excerpts
curl "https://api.particle.pro/v1/alerts/deliveries/Dl9XYZ?view=detailed" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Both are keyed only by the resource’s own ID — the parent alert ID is deliberately absent from the URL so a link can be shared without revealing which alert it came from. Possession of the link grants read access; the IDs are unguessable. The response fidelity then depends on who’s asking:
  • The alert’s owners get the full payload: transcript windows, mention variants, salience, and speaker roles. An API key qualifies only if it’s scoped to the alert’s project — a key from another project, even in the same organization, gets the reduced payload; a signed-in user qualifies if they’re a member of the alert’s organization. On the single-match endpoint (GET /v1/alerts/matches/{id}) owners also get the match’s deliveries array — the per-channel send audit — which is stripped for everyone else.
  • Everyone else gets a reduced public payload — the entity, the episode metadata, detected_at, mention_count, and the AI summary — enough to render a result card, with the internal scoring and configuration stripped.
On the delivery endpoint, view controls excerpt depth for members: summary (default) omits transcript windows; detailed includes them. Use detailed to render a full results page where each match expands to the spoken excerpt.

​
Stop delivery

Two ways to stop an alert:
  • Pause it — PATCH /v1/alerts/{id} with is_active: false. The alert keeps its history and can be resumed. See Update, pause, and delete.
  • One-click disable from an email — every alert email has a Disable this alert link in its footer carrying a single-use token. Opening it shows the alert it controls; confirming flips is_active to false. The recipient doesn’t need a Particle account — token possession is the access factor. Replaying an already-used link is harmless: it returns the alert’s current is_active state with an already_disabled flag, so an alert that was re-enabled after the first click correctly shows as active again.