Get a single alert match

Returns one match with full hydration — transcript Windows, source-episode metadata, and the deliveries that included this match. The URL is keyed only by the match ID so a result link can be shared publicly without leaking the alert identifier. Use this for per-match landing pages opened from a digest or results list. URL possession is the access factor; authenticated org members see the full payload while unauthenticated and non-member callers see a reduced public payload (entity + episode, no transcript dialogue). Single-match only: digests (daily/weekly) embed many matches and should be fetched via GET /v1/alerts/deliveries/{id}?view=detailed.

get/v1/alerts/matches/{id}

Request

Base URL: https://api.particle.pro
URL: https://api.particle.pro/v1/alerts/matches/{id}
Auth: none required

Path parameters

idstring required

Match ID

Response

alert_idstring required

ID of the parent alert.

detected_atstring date-time required

entity_idstring required

entity_typestring required

Type of the watched target: PERSON, COMPANY, or KNOWLEDGE_GRAPH_ENTITY for entity alerts, KEYWORD for KEYWORD_MENTION alerts.

idstring required

is_backfilledboolean

True for matches written by the post-create historical sweep. Backfilled matches are real matches the live pipeline would have produced, with DetectedAt set to the source episode's publish time. They never trigger delivery (no email is sent) — the field lets the UI label them so users can distinguish 'past' from 'going-forward' matches.

keywordstring

KEYWORD_MENTION matches only: the phrase this match fired on. It stays the phrase that matched even if the alert's keyword is later edited.

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

Inherited from the parent alert's kind so clients can render mention vs appearance semantics without a follow-up alert lookup. Match payloads from ENTITY_MENTION and KEYWORD_MENTION alerts carry mention_count and mention_variants; PODCAST_SPEAKER matches carry roles and a line-count in mention_count.

llm_summarystring

AI-generated narrative summary of this match with prior-mention context from the past 7 days for the same (alert, entity). Generated asynchronously after match creation. Absent (field omitted) when the summarizer hasn't processed the row yet OR when the LLM exhausted its retry budget — clients should treat both states the same: no summary to render. Visible to both org members and the public landing-page tier; the summary describes the mention itself, not the alert configuration.

mention_countinteger required

mention_variantsstring[] nullable

monitor_idstring required

Deprecated — use alert_id. ID of the parent alert.

relevance'on_target' | 'incidental'

How this match relates to the watched entity, classified by the summarizer: on_target (the entity is the mention's subject or a substantive reference) or incidental (a correct but passing reference in service of another story). Absent when unjudged. Lets a client tell a substantive mention from a fly-by one. (A third internal verdict, wrong_entity, marks knowledge-graph name collisions; those matches are suppressed before delivery and never appear here.)

rolesstring[] nullable

Canonical speaker role(s) the matched entity appeared as, drawn from the alert's speaker roles: by default GUEST, PANELIST, CORRESPONDENT, AUDIENCE, or SOUNDBITE_SPEAKER (an excerpted clip of them, not a live appearance), and HOST only when speaker_roles includes it. Raw STT/LLM labels like CALLER, REPORTER, LISTENER are normalized to these buckets on write. Populated only for PODCAST_SPEAKER matches; sorted alphabetically for deterministic order.

source_idstring required

source_typestring required

truncatedboolean

Changes

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