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/?view=detailed.

GET /v1/alerts/matches/{id}

cURL

cURL

curl "https://api.particle.pro/v1/alerts/matches/{id}"

200

{
  "alert_id": "<string>",
  "deliveries": [
    {
      "channel": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "status": "<string>",
      "error_message": "<string>",
      "sent_at": "2023-11-07T05:31:56Z"
    }
  ],
  "detected_at": "2023-11-07T05:31:56Z",
  "entity_id": "<string>",
  "entity_type": "<string>",
  "id": "<string>",
  "kind": "ENTITY_MENTION",
  "mention_count": 123,
  "monitor_id": "<string>",
  "source_id": "<string>",
  "source_type": "<string>",
  "episode": {
    "podcast_id": "<string>",
    "podcast_title": "<string>",
    "title": "<string>",
    "apple_podcasts_url": "<string>",
    "audio_url": "<string>",
    "duration_seconds": 123,
    "explicit": true,
    "image_url": "<string>",
    "podcast_bias": "EXTREME_LEFT",
    "podcast_image_url": "<string>",
    "podcast_popularity": 123,
    "podcast_popularity_badge": "Top Podcast",
    "podcast_slug": "<string>",
    "published_at": "2023-11-07T05:31:56Z",
    "slug": "<string>"
  },
  "is_backfilled": true,
  "keyword": "<string>",
  "llm_summary": "<string>",
  "mention_variants": [
    "<string>"
  ],
  "relevance": "on_target",
  "roles": [
    "<string>"
  ],
  "truncated": true,
  "windows": [
    {
      "end_seconds": 123,
      "lines": [
        {
          "end_seconds": 123,
          "start_seconds": 123,
          "text": "<string>",
          "is_mention": true,
          "number": 123,
          "role": "<string>",
          "speaker": "<string>"
        }
      ],
      "start_seconds": 123,
      "clip_description": "<string>",
      "clip_id": "<string>",
      "clip_intro_statement": "<string>",
      "clip_title": "<string>",
      "clip_type": "<string>",
      "segment_description": "<string>",
      "segment_id": "<string>",
      "segment_summary": "<string>",
      "segment_title": "<string>",
      "segment_type": "<string>"
    }
  ]
}

Prefer the terminal? This endpoint is also a command in the Particle CLI: pick Particle CLI in the request example’s language menu. Install the Particle CLI.

Path Parameters

id · string · required

Match ID

Response

200

application/json

OK

alert_id · string · required

ID of the parent alert.

deliveries · object[] | null · required

Show child attributes

detected_at · string<date-time> · required

entity_id · string · required

entity_type · string · required

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

id · string · required

kind · enum<string> · 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.

Available options: ENTITY_MENTION, PODCAST_SPEAKER, KEYWORD_MENTION

mention_count · integer<int64> · required

monitor_id · string · required

Deprecated — use alert_id. ID of the parent alert.

source_id · string · required

source_type · string · required

episode · object

Optional episode + podcast metadata embedded so a single response renders a card without a follow-up /v1/episodes/{id} call. Populated for preview-sample matches (POST /v1/projects/{projectId}/alerts/preview's GET response) and for the landing-page GETs (GET /v1/alerts/deliveries/{id} in both summary and detailed views, GET /v1/alerts/matches/{id}); absent on the paginated live matches list.

Show child attributes

is_backfilled · boolean

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.

keyword · string

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.

llm_summary · string

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_variants · string[] | null

relevance · enum<string>

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.)

Available options: on_target, incidental

roles · string[] | null

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.

truncated · boolean

windows · object[] | null

Show child attributes