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

# search_episodes

`POST /search_episodes`

## Request

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

Search episodes in the active workspace by show, status, free-text query (title, show notes, OR guest_name), season + episode number, season/episode presence, or published date range. When the user names a guest (e.g., "Orlagh Reynolds", "Reynolds"), use `query` — it ILIKE-matches against guest_name as well as title/notes, so partial spellings hit. Each item includes primary_contacts from episode_contacts, so compare episodes to interview bookings by contact_id instead of free-text guest_name when answering coverage questions. When the user gives season + episode coordinates ("S4 E13", "season 4, episode 13"), pass both as `season` and `episode` integer filters. For RSS-import cleanup/enrichment questions about MISSING fields ("episodes with no season", "no season but has an episode number", "episodes missing an episode number"), use the boolean presence filters `has_season` and `has_episode` (false = field IS NULL, true = field IS NOT NULL) — never pass a season/episode number to mean "unset". Read `total` for the exact count. For Planned Episodes, use status=planned; these have null season/episode until activate_planned_episode is called. For "latest", "current", "recent", or "what episodes are published", use status=published and a small limit; results sort by published_date newest first, then created_at. The `total` field is the exact count across all pages — use it for "how many episodes" answers, never items.length when has_more is true.

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