---
title: "match_episodes"
method: POST
path: "/match_episodes"
tags: ["episodes"]
---

# match_episodes

`POST /match_episodes`

## Request

- Base URL: `https://app.podmule.com/api/v1`
- URL: `https://app.podmule.com/api/v1/match_episodes`
- Auth: HTTP bearer

Bulk-resolve many episodes in ONE call by a known set of values — instead of looping get_episode N times. Supply filters of {field, values[], mode}: exact (IN — for prefixed ids ep_/sh_, status, season, episode) or contains (case-insensitive literal substring — for title, guest_name). Contains-eligible fields: title, guest_name. Combine filters with 'any' (OR, default) or 'all' (AND). Returns matches (with matched_by), unmatched, and truncated. Each row includes guest_contacts — the AUTHORITATIVE contacts linked to the episode (id + name + role). When guest_contacts is non-empty, use those contact ids for any contact/interview lookup (e.g. list_interviews) — do NOT name-match on guest_name, which is only a transcript guess. detail:'full' equals summary (no transcript fan-out) — use get_episode for transcripts/chapters. Caps: ≤50 values/filter, ≤5 filters, ≤200 rows. For reconciliation against a caller-supplied set, not large scans (use search_episodes to browse).

## Request body

- unknown

## Response `200`

Capability output wrapped in `{ data }`.

- object
  - `data` unknown, required

## Other responses

- `400`: Invalid input — Zod validation failed.
- `401`: Missing, malformed, or audience-mismatched bearer token.
- `403`: Token is valid but lacks the required scope.
- `404`: Capability not registered, or referenced resource not found.
- `429`: Rate limit exceeded. Retry after the period in `Retry-After`.
- `500`: Internal error.

---

[API](https://skmtc.dev/podmule/apis/podmule-api.md) · [All operations](https://skmtc.dev/podmule/apis/podmule-api/llms.txt) · [OpenAPI document](https://skmtc.dev/podmule/apis/podmule-api/revisions/844ae61495fa?raw)