Alert Matches

GET https://api.podengine.ai/api/v1/alerts/matches

Get your team's alert matches, one per episode, newest first. Each match lists its mentions with the time, a snippet, the ad and wrong-person check labels, and a link that plays from that moment. Set includeFiltered to also see the episodes and mentions your alert filters removed, and why.

API token required Markdown for LLMs

OpenAPI spec

Example request

Install & configure

curl -X GET "https://api.podengine.ai/api/v1/alerts/matches" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_TOKEN"

const options = {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"
  }
};

fetch("https://api.podengine.ai/api/v1/alerts/matches", options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"
}

response = requests.get("https://api.podengine.ai/api/v1/alerts/matches", headers=headers)
print(response.json())

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "YOUR_API_TOKEN");
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var response = await client.GetAsync("https://api.podengine.ai/api/v1/alerts/matches");
var data = await response.Content.ReadAsStringAsync();
Console.WriteLine(data);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.podengine.ai/api/v1/alerts/matches", nil)
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "YOUR_API_TOKEN")
	
	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

import { PodEngine } from '@podengine/sdk';

const pe = new PodEngine({ apiKey: process.env.PODENGINE_API_KEY });

const data = await pe.alerts.getAlertEpisodeMatches();

console.log(data);

import os

from podengine import PodEngine

pe = PodEngine(api_key=os.environ["PODENGINE_API_KEY"])

data = pe.alerts.get_alert_episode_matches()

print(data)

200

Example response

{
  "status": "OK",
  "data": {
    "options": {
      "alertConfigId": "string",
      "includeFiltered": "string",
      "page": 1,
      "pageSize": 1
    },
    "total": 0,
    "matches": [
      {
        "id": "string",
        "alertConfig": {
          "id": "string",
          "name": "string",
          "type": "person"
        },
        "status": "kept",
        "filterReasons": [
          "ad"
        ],
        "episode": {
          "id": "string",
          "slug": "string",
          "title": "string",
          "publishedAt": "2026-01-15T09:30:00.000Z",
          "imageUrl": "string"
        },
        "podcast": {
          "id": "string",
          "slug": "string",
          "title": "string"
        },
        "appearance": {
          "role": "guest",
          "source": "people_data"
        },
        "subjectCheck": "checked",
        "mentionCount": 0,
        "keptMentionCount": 0,
        "syndicatedEpisodeIds": [
          "string"
        ],
        "firstMatchedAt": "2026-01-15T09:30:00.000Z",
        "mentions": [
          {
            "id": "string",
            "startSecond": 0,
            "snippet": "string",
            "passesFilters": true,
            "filterReasons": [
              "ad"
            ],
            "labels": [
              {
                "classifier": "isAd",
                "label": "string",
                "probability": 0,
                "filteredOut": true
              }
            ],
            "playUrl": "https://example.com"
          }
        ]
      }
    ]
  }
}

Request

Query parameters

alertConfigIdstring

Only matches for this alert configuration.

includeFilteredstring

Include episodes and mentions the alert filters removed, with the labels that removed them. Defaults to false.

pagenumbermin 1

Page of episodes to return. Defaults to 1.

pageSizenumber1 – 50

Episodes per page, up to 50. Defaults to 25.

Response

200 application/json

statusliteral: OKrequired

dataobjectrequired3 fields

optionsobjectrequired4 fields

alertConfigIdstring

Only matches for this alert configuration.

includeFilteredstring

Include episodes and mentions the alert filters removed, with the labels that removed them. Defaults to false.

pagenumbermin 1

Page of episodes to return. Defaults to 1.

pageSizenumber1 – 50

Episodes per page, up to 50. Defaults to 25.

totalnumberrequired

Episodes matching the options, across all pages.

matchesarray of objectrequired13 fields

idstringrequired

alertConfigobjectrequired3 fields

idstringrequired

namestringrequired

typeenumrequired

personcompanycustom-keyword

statusenumrequired

keptfiltered

filterReasonsarray of enumrequired

Why the episode was filtered: the reasons of its mentions combined. Empty when kept.

adnot_subjectuncheckedlegacy_context_check

episodeobjectrequired5 fields

idstringrequired

slugstringrequired

titlestringrequired

publishedAtdaterequired

imageUrlstringrequirednullable

podcastobjectrequired3 fields

idstringrequired

slugstringrequired

titlestringrequired

appearanceobjectrequirednullable2 fields

roleenumrequirednullable

guesthostmentionedunknown

sourceenumrequired

people_datatitle_description

subjectCheckenumrequirednullable

Person and company alerts: "checked" when mentions about someone else with the same name are filtered out, "unverified" when they are not (the alert has no "Who is this?" note that passed the check). Null for keyword alerts.

checkedunverified

mentionCountnumberrequired

keptMentionCountnumberrequired

syndicatedEpisodeIdsarray of stringrequired

firstMatchedAtdaterequired

mentionsarray of objectrequired7 fields

Mentions that pass the alert filters, earliest first; filtered ones too when includeFiltered is set.

idstringrequired

startSecondnumberrequirednullable

snippetstringrequired

passesFiltersbooleanrequired

filterReasonsarray of enumrequired

adnot_subjectuncheckedlegacy_context_check

labelsarray of objectrequired4 fields

classifierenumrequired

isAdisSubject

labelstringrequired

The classifier label, e.g. "sponsor_read" or "not_about".

probabilitynumberrequired0 – 1

filteredOutbooleanrequired

Whether this label removed the mention under the alert filters.

playUrlstringrequiredurl