> ## 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. # Related Episodes > Episodes from other shows that cover the same story or subject as a given episode, ranked by content, shared entities, shared topics and a shared story — with the reasons attached. Given one episode, which episodes elsewhere covered the same story or subject? Particle API answers with a ranked, explainable list computed live from the episode's own content and the structured signals around it: the salient entities it is about, the topics it was classified under and the news story it was linked to. Every result carries a calibrated score, a coarse band, and, on request, the specific signals behind the match, including any shared guests and how far apart the two episodes were published. Unlike related podcasts, related episodes are not precomputed: the candidate set comes from a nearest-neighbour search over episode content at request time, and the result is cached for a day (episodes do not change once ingested). ## List related episodes ```bash theme={"dark"} curl -s -H "X-API-Key: $PARTICLE_API_KEY" \ "https://api.particle.pro/v1/podcasts/episodes/author-interview-sebastian-barry/related?include=basis&published_within_days=30&limit=3" ``` ```json Response (truncated) theme={"dark"} { "data": [ { "episode": { "id": "…", "slug": "…", "title": "…", "published_at": "2026-09-01T00:00:00Z", "podcast": { "id": "…", "title": "…", "slug": "…" } }, "score": 0.82, "band": "strong", "basis": { "content_similarity": 0.71, "shared_entity_count": 2, "shared_entities": [ { "id": "…", "name": "…" } ], "shared_topic_count": 1, "shared_story_count": 1, "shared_guest_count": 0, "days_apart": 2.4 } } ], "has_more": true, "cursor": "r.…" } ``` | Parameter | Meaning | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` (path) | Episode slug or ID — the same identifiers every episode endpoint accepts. | | `same_podcast` | Admit episodes of the same show. Off by default: a show's own episodes are its [episode list](/podcasts/episodes), not its related content. | | `published_within_days` | Only episodes published within this many days of the query episode, on either side, when the query episode has a `published_at`; an undated query episode ignores the window. Omit for no window; use 7–30 for "who else covered this story this week". | | `include` | `basis` attaches the explanation object to every result. Omit it for the lean form (episode, score, band). | | `limit`, `cursor` | Standard pagination over the ranked set (up to 50 related episodes per query). | ## Reading a result | Field | Meaning | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `score` | Fused relatedness in (0, 1], calibrated so that higher values are more likely to be judged related by an editor, on the same footing as the show-level score. Comparable across episodes. | | `band` | `strong` (the same story or subject), `moderate` (overlapping subject), `weak` (a loose connection). Branch on this rather than on raw score thresholds. | | `basis.content_similarity` | Cosine similarity of the two episodes' content centroids, each derived from their transcripts. Omitted when either episode has no embedded content — an absent signal, not a low one. | | `basis.shared_entity_count` / `basis.shared_entities` | Salient knowledge-graph entities both episodes are about; up to three are named, most significant first. Entity ids are valid on `GET /v1/entities/{id}`. | | `basis.shared_topic_count` | Taxonomy topics both episodes were classified under. | | `basis.shared_story_count` | News stories both episodes were linked to. Non-zero means the two episodes discuss the same story. | | `basis.shared_guest_count` | Guests who appear in both episodes. | | `basis.days_apart` | Absolute difference between the publish dates, in days. Reported for context; use `published_within_days` to keep results to one news cycle. | Results are restricted to the query episode's language. An episode with no embedded content yet returns `200` with an empty `data` array, not `404`. ## Choosing the right endpoint | You want… | Use | | ---------------------------------------- | -------------------------------------------------------------- | | Episodes like this episode, across shows | `GET /v1/podcasts/episodes/{id}/related` (this page) | | Shows like this show | [`GET /v1/podcasts/{id}/related`](/podcasts/related) | | Dialogue about a topic or idea | [`GET /v1/podcasts/episodes/search`](/podcasts/episode-search) | | Every line naming a specific entity | [`GET /v1/podcasts/mentions`](/podcasts/mentions) | | More episodes of the same show | [`GET /v1/podcasts/{id}/episodes`](/podcasts/episodes) | ## How it is computed Each episode's content segments are embedded at ingest and folded into one content centroid. A request runs a nearest-neighbour search over those centroids (same language, optional publish window, the query's own show excluded by default), then reranks the candidates on the structured signals: salience-weighted shared entities, shared taxonomy topics and a shared news story. The ranker's weights are fixed constants fitted on editorial judgements of episode pairs and checked against held-out same-story and shared-entity pairs, the same procedure as the show-level ranker. The score is the calibrated probability that an editor would call the two episodes related, and the bands are cut on that probability.