> ## Documentation Index > Fetch the complete documentation index at: https://docs.particle.pro/llms.txt > Use this file to discover all available pages before exploring further. # Episodes > Discover and filter episodes across the catalog, with rich per-episode sub-resources. The cross-podcast episode endpoint is the primary discovery tool. Filter by podcast, entity, company, language, date range, or duration. Every episode comes with sub-resources for transcripts, segments, clips, speakers, entities, and topics. Tracking *new* episodes as they're ingested? Don't poll this list with `published_after` — use the [episode feed](/podcasts/feed), a resumable poll that returns each new episode exactly once, or the real-time [episode stream](/podcasts/stream) (Enterprise). Available to MCP agents as [`particle_podcast_list_episodes`](/mcp/tools/podcasts/podcast-list-episodes) and (per-episode) [`particle_podcast_get_episode`](/mcp/tools/podcasts/podcast-get-episode). ## List episodes ```bash curl theme={"dark"} curl "https://api.particle.pro/v1/podcasts/episodes?entity_id=sam-altman&limit=3" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```js JavaScript theme={"dark"} const url = new URL("https://api.particle.pro/v1/podcasts/episodes"); url.searchParams.set("entity_id", "sam-altman"); url.searchParams.set("limit", "3"); const res = await fetch(url, { headers: { "X-API-Key": process.env.PARTICLE_API_KEY }, }); const { data } = await res.json(); ``` ```python Python theme={"dark"} res = httpx.get( "https://api.particle.pro/v1/podcasts/episodes", params={"entity_id": "sam-altman", "limit": 3}, headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]}, ) data = res.json()["data"] ``` ```jsonc Response (truncated) theme={"dark"} { "data": [ { "id": "78cgekLUjCJBUZbj3s5K8Y", "title": "WHCD Shooting Aftermath, Musk and Altman Face-Off, Spirit Airlines Bailout", "podcast": { "id": "QpMz7GYKfSNuUa6zKXA4Q", "title": "Pivot" }, "published_at": "2026-04-28T10:00:00Z", "duration_seconds": 4206, "has_transcript": true, "segment_count": 21, "clip_count": 8, "entity_count": 146, "speakers": [ /* … */ ] } // … ], "has_more": true, "cursor": "…" } ``` The `has_transcript`, `segment_count`, `clip_count`, and `entity_count` fields tell you what enrichment data is available before you fetch any sub-resource. ## Filter parameters | Parameter | Description | Example | | ------------------------------- | ------------------------------------------------------- | ---------------------------------------- | | `podcast_id` | Slug, ID, or numeric iTunes ID; restrict to one podcast | `?podcast_id=pivot` | | `entity_id` | Slug or ID; episodes featuring or mentioning the entity | `?entity_id=sam-altman` | | `company_id` | Slug, domain, or ID; episodes featuring a company | `?company_id=nvidia` | | `language` | ISO 639-1 code | `?language=en` | | `published_after` | ISO 8601 timestamp | `?published_after=2026-04-01T00:00:00Z` | | `published_before` | ISO 8601 timestamp | `?published_before=2026-04-30T00:00:00Z` | | `has_transcript` | Limit to transcribed episodes | `?has_transcript=true` | | `min_duration` / `max_duration` | Bounds in seconds | `?min_duration=1800&max_duration=7200` | Combine freely — for long-form transcribed Sam Altman episodes from this month, for example: ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/episodes?\ entity_id=sam-altman&\ has_transcript=true&\ min_duration=1800&\ published_after=2026-04-01T00:00:00Z&\ limit=10" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ## Get a single episode ```bash curl theme={"dark"} curl "https://api.particle.pro/v1/podcasts/episodes/78cgekLUjCJBUZbj3s5K8Y" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` The full Episode response is documented in the [API reference](/api-reference/introduction). ## Episodes for a specific podcast A convenience shape of `list-episodes` filtered by podcast: ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/pivot/episodes?limit=10" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ## Sub-resources Every episode exposes its enrichment data as sub-resources: | Endpoint | Returns | | ------------------------------------------- | ---------------------------------------------------- | | `GET .../episodes/{id}/transcript` | Diarized dialogue (full transcript) | | `GET .../episodes/{id}/transcript/words` | Word-level timestamps | | `GET .../episodes/{id}/transcript/mentions` | Lines around mentions of an entity | | `GET .../episodes/{id}/segments` | Structural sections (intros, ads, topic discussions) | | `GET .../episodes/{id}/clips` | Highlight clips | | `GET .../episodes/{id}/speakers` | Identified speakers with speaking duration | | `GET .../episodes/{id}/entities` | Mentioned entities ranked by salience | | `GET .../episodes/{id}/topics` | Topic classifications | ## Speakers ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/episodes/78cgekLUjCJBUZbj3s5K8Y/speakers" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```jsonc Response (truncated) theme={"dark"} { "data": [ { "name": "Kara Swisher", "role": "HOST", "speaking_duration_seconds": 1955.12, "entity_slug": "kara-swisher" }, { "name": "Scott Galloway", "role": "HOST", "speaking_duration_seconds": 1986.09, "entity_slug": "scott-galloway" }, { "name": "Elie Honig", "role": "SOUNDBITE_SPEAKER", "speaking_duration_seconds": 50.30, "entity_slug": "elie-honig" } // … ] } ``` Roles include `HOST`, `CO_HOST`, `GUEST`, `PANELIST`, `CORRESPONDENT`, `SOUNDBITE_SPEAKER`, and `ADVERTISER`. Filter by role on your side if you only want hosts and guests. The `entity_slug` (when present) bridges to the [knowledge graph](/knowledge-graph/entities). ## Entities Returns people, organizations, places, products, and concepts mentioned in the episode, ranked by **salience** — a relative relevance score for that episode where higher values indicate the entity is more central to the discussion. ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/episodes/78cgekLUjCJBUZbj3s5K8Y/entities" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```jsonc Response (truncated) theme={"dark"} { "data": [ { "entity": { "id": "1GmOP1C2UZtpnHKPoc", "slug": "openai", "name": "OpenAI" }, "salience": 0.0061, "occurrences": 11 }, { "entity": { "id": "1GmOP1C3KLh", "slug": "anthropic", "name": "Anthropic" }, "salience": 0.00024, "occurrences": 10 }, { "entity": { "id": "17PzxG1t12xzno", "slug": "sam-altman", "name": "Sam Altman" }, "salience": 0.00016, "occurrences": 5 } // … ] } ``` For the actual dialogue around mentions, see [transcripts → mentions](/podcasts/transcripts#transcript-mentions). ## Topics ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/episodes/78cgekLUjCJBUZbj3s5K8Y/topics" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` Topics are drawn from the hierarchical [topics taxonomy](/knowledge-graph/topics) — useful for routing episodes to category-specific feeds. ## Related * [Transcripts](/podcasts/transcripts) — dialogue, words, mentions, SRT * [Segments & clips](/podcasts/segments-and-clips) — structural breakdown and highlights * [Knowledge graph → entities](/knowledge-graph/entities) — follow speakers and topics across the catalog