# Alert Matches

> Pod Engine API endpoint reference, optimized for LLM consumption.
> Auto-generated from the source-of-truth endpoint registry.
>
> Category: Alerts
> Source: https://www.podengine.ai/api-docs/get-alert-matches.md
> Interactive HTML docs: https://www.podengine.ai/api-docs/get-alert-matches
> Full API reference (all endpoints): https://www.podengine.ai/api-docs/llms.txt

**Base URL:** `https://api.podengine.ai`
**Auth:** Requires a Bearer token: `Authorization: Bearer YOUR_API_KEY`

---

#### GET /api/v1/alerts/matches
**Alert 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.

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

**Query schema:**
```json
{
  "type": "object",
  "properties": {
    "alertConfigId": {
      "description": "Only matches for this alert configuration.",
      "type": "string"
    },
    "includeFiltered": {
      "description": "Include episodes and mentions the alert filters removed, with the labels that removed them. Defaults to false.",
      "type": "boolean"
    },
    "page": {
      "description": "Page of episodes to return. Defaults to 1.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "pageSize": {
      "description": "Episodes per page, up to 50. Defaults to 25.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "additionalProperties": false
}
```

**Response schema:**
```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "OK"
      ]
    },
    "data": {
      "type": "object",
      "properties": {
        "options": {
          "type": "object",
          "properties": {
            "alertConfigId": {
              "description": "Only matches for this alert configuration.",
              "type": "string"
            },
            "includeFiltered": {
              "description": "Include episodes and mentions the alert filters removed, with the labels that removed them. Defaults to false.",
              "type": "boolean"
            },
            "page": {
              "description": "Page of episodes to return. Defaults to 1.",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "pageSize": {
              "description": "Episodes per page, up to 50. Defaults to 25.",
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          },
          "additionalProperties": false
        },
        "total": {
          "type": "number",
          "description": "Episodes matching the options, across all pages."
        },
        "matches": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "alertConfig": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "person",
                      "company",
                      "custom-keyword"
                    ]
                  }
                },
                "required": [
                  "id",
                  "name",
                  "type"
                ],
                "additionalProperties": false
              },
              "status": {
                "type": "string",
                "enum": [
                  "kept",
                  "filtered"
                ]
              },
              "filterReasons": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "ad",
                    "not_subject",
                    "unchecked",
                    "legacy_context_check"
                  ]
                },
                "description": "Why the episode was filtered: the reasons of its mentions combined. Empty when kept."
              },
              "episode": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  },
                  "publishedAt": {},
                  "imageUrl": {
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "slug",
                  "title",
                  "publishedAt",
                  "imageUrl"
                ],
                "additionalProperties": false
              },
              "podcast": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "slug",
                  "title"
                ],
                "additionalProperties": false
              },
              "appearance": {
                "nullable": true,
                "type": "object",
                "properties": {
                  "role": {
                    "nullable": true,
                    "type": "string",
                    "enum": [
                      "guest",
                      "host",
                      "mentioned",
                      "unknown"
                    ]
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "people_data",
                      "title_description"
                    ]
                  }
                },
                "required": [
                  "role",
                  "source"
                ],
                "additionalProperties": false
              },
              "subjectCheck": {
                "nullable": true,
                "description": "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.",
                "type": "string",
                "enum": [
                  "checked",
                  "unverified"
                ]
              },
              "mentionCount": {
                "type": "number"
              },
              "keptMentionCount": {
                "type": "number"
              },
              "syndicatedEpisodeIds": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "firstMatchedAt": {},
              "mentions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "startSecond": {
                      "nullable": true,
                      "type": "number"
                    },
                    "snippet": {
                      "type": "string"
                    },
                    "passesFilters": {
                      "type": "boolean"
                    },
                    "filterReasons": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "ad",
                          "not_subject",
                          "unchecked",
                          "legacy_context_check"
                        ]
                      }
                    },
                    "labels": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "classifier": {
                            "type": "string",
                            "enum": [
                              "isAd",
                              "isSubject"
                            ]
                          },
                          "label": {
                            "type": "string",
                            "description": "The classifier label, e.g. \"sponsor_read\" or \"not_about\"."
                          },
                          "probability": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1
                          },
                          "filteredOut": {
                            "type": "boolean",
                            "description": "Whether this label removed the mention under the alert filters."
                          }
                        },
                        "required": [
                          "classifier",
                          "label",
                          "probability",
                          "filteredOut"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "playUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  },
                  "required": [
                    "id",
                    "startSecond",
                    "snippet",
                    "passesFilters",
                    "filterReasons",
                    "labels",
                    "playUrl"
                  ],
                  "additionalProperties": false
                },
                "description": "Mentions that pass the alert filters, earliest first; filtered ones too when includeFiltered is set."
              }
            },
            "required": [
              "id",
              "alertConfig",
              "status",
              "filterReasons",
              "episode",
              "podcast",
              "appearance",
              "subjectCheck",
              "mentionCount",
              "keptMentionCount",
              "syndicatedEpisodeIds",
              "firstMatchedAt",
              "mentions"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "options",
        "total",
        "matches"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "status",
    "data"
  ],
  "additionalProperties": false
}
```

---

## See also

- All endpoints in one file: https://www.podengine.ai/api-docs/llms.txt
- Full reference with every schema inlined: https://www.podengine.ai/api-docs/llms-full.txt
- OpenAPI 3.1 spec: https://www.podengine.ai/api-docs/openapi.json
- Get an API key: https://www.podengine.ai/get-started
- Support: support@podengine.ai