Search podcast episode content

To find podcasts (shows) by name or topic, use /v1/podcasts/search?q=…. This endpoint searches inside episode dialogue — by meaning (semantic_search), by exact phrase (keyword_search), or both at once (hybrid). Each result is a segment of an episode, returned with bounded preview windows of dialogue and any highlight clips that overlap the segment.

For “every line about a person or company” use /v1/podcasts/mentions instead — that endpoint returns episode-grouped mention windows with line-level highlights and is shaped for the read-everything-about-X use case. entity_id and company_id here narrow the result set to episodes featuring the resolved entity, but the ranking still comes from semantic_search / keyword_search.

GET /v1/podcasts/episodes/search

cURL

cURL

curl -H "X-API-Key: $PARTICLE_API_KEY" \
  "https://api.particle.pro/v1/podcasts/episodes/search?keyword_match=required&context=1&limit=25"

200

{
  "data": [
    {
      "episode": {
        "id": "<string>",
        "title": "<string>",
        "podcast": {
          "id": "<string>",
          "title": "<string>",
          "best_rank": {
            "captured_at": "2023-11-07T05:31:56Z",
            "chart_type": "top_podcasts",
            "rank": 123,
            "source": "apple",
            "category_slug": "<string>",
            "country": "<string>"
          },
          "image_url": "<string>",
          "popularity": 123,
          "publisher": {
            "id": "<string>",
            "name": "<string>",
            "slug": "<string>"
          },
          "slug": "<string>"
        },
        "published_at": "2023-11-07T05:31:56Z",
        "slug": "<string>"
      },
      "match": {
        "source": "<string>",
        "relevance_score": 123
      },
      "segment": {
        "duration_seconds": 123,
        "end_seconds": 123,
        "id": "<string>",
        "number": 123,
        "start_seconds": 123,
        "title": "<string>",
        "type": "<string>",
        "audio_url": "<string>",
        "description": "<string>",
        "end_line": 123,
        "episode": {
          "id": "<string>",
          "title": "<string>",
          "podcast": {
            "id": "<string>",
            "title": "<string>",
            "best_rank": {
              "captured_at": "2023-11-07T05:31:56Z",
              "chart_type": "top_podcasts",
              "rank": 123,
              "source": "apple",
              "category_slug": "<string>",
              "country": "<string>"
            },
            "image_url": "<string>",
            "popularity": 123,
            "publisher": {
              "id": "<string>",
              "name": "<string>",
              "slug": "<string>"
            },
            "slug": "<string>"
          },
          "published_at": "2023-11-07T05:31:56Z",
          "slug": "<string>"
        },
        "read_type": "<string>",
        "start_line": 123,
        "summary": "<string>"
      },
      "windows": [
        {
          "end_seconds": 123,
          "lines": [
            {
              "end_seconds": 123,
              "number": 123,
              "speaker": "<string>",
              "start_seconds": 123,
              "text": "<string>",
              "is_match": true,
              "is_mention": true,
              "matched_terms": [
                "<string>"
              ],
              "role": "<string>"
            }
          ],
          "start_seconds": 123,
          "is_preview": true
        }
      ],
      "clips": [
        {
          "duration_seconds": 123,
          "end_seconds": 123,
          "engagement_score": 123,
          "id": "<string>",
          "start_seconds": 123,
          "title": "<string>",
          "audio_url": "<string>",
          "description": "<string>",
          "episode": {
            "id": "<string>",
            "title": "<string>",
            "podcast": {
              "id": "<string>",
              "title": "<string>",
              "best_rank": {
                "captured_at": "2023-11-07T05:31:56Z",
                "chart_type": "top_podcasts",
                "rank": 123,
                "source": "apple",
                "category_slug": "<string>",
                "country": "<string>"
              },
              "image_url": "<string>",
              "popularity": 123,
              "publisher": {
                "id": "<string>",
                "name": "<string>",
                "slug": "<string>"
              },
              "slug": "<string>"
            },
            "published_at": "2023-11-07T05:31:56Z",
            "slug": "<string>"
          },
          "intro_statement": "<string>",
          "segment": {
            "id": "<string>",
            "title": "<string>",
            "type": "<string>"
          },
          "speaker": {
            "name": "<string>",
            "entity": {
              "id": "<string>",
              "name": "<string>",
              "slug": "<string>",
              "company": {
                "id": "<string>",
                "domain": "<string>",
                "ticker": "<string>"
              },
              "description": "<string>",
              "image_url": "<string>",
              "person": {
                "id": "<string>",
                "company": "<string>",
                "image_url": "<string>",
                "title": "<string>"
              },
              "type": {
                "name": "<string>",
                "slug": "<string>"
              },
              "wikipedia_url": "<string>"
            },
            "person": {
              "id": "<string>",
              "name": "<string>",
              "description": "<string>",
              "image_url": "<string>",
              "slug": "<string>"
            },
            "role": "<string>"
          },
          "type": "SPICY"
        }
      ]
    }
  ],
  "has_more": true,
  "company": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "domain": "<string>",
    "image_mode": "AUTOMATIC",
    "image_url": "<string>",
    "slug": "<string>",
    "ticker": "<string>"
  },
  "cursor": "<string>",
  "diagnostics": {
    "outcome": "filter_too_narrow",
    "summary": "<string>",
    "filters": [
      {
        "parameter": "<string>",
        "emptied_results": true,
        "remedy": "<string>",
        "retry_with": {},
        "value": "<string>"
      }
    ],
    "next_steps": [
      "<string>"
    ]
  },
  "entity": {
    "id": "<string>",
    "name": "<string>",
    "slug": "<string>",
    "company": {
      "id": "<string>",
      "domain": "<string>",
      "ticker": "<string>"
    },
    "description": "<string>",
    "image_url": "<string>",
    "person": {
      "id": "<string>",
      "company": "<string>",
      "image_url": "<string>",
      "title": "<string>"
    },
    "type": {
      "name": "<string>",
      "slug": "<string>"
    },
    "wikipedia_url": "<string>"
  }
}

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

Pass your API key in the X-API-Key header (recommended).

Query Parameters

semantic_search · string

Vector-similarity search by meaning. Express the query the way you'd describe the topic to a colleague — paraphrase tolerant, finds segments that express the same idea in different vocabulary. Combine with keyword_search for hybrid ranking. Describe a topic, not a name: to find a specific person or company, filter with entity_id / company_id (or use /v1/podcasts/mentions for every line about them) — and for an exact token like a ticker, use keyword_search.

Maximum string length: 500

keyword_search · string

BM25 lexical search over dialogue. Use when an exact token must appear verbatim — tickers, drug names, product codes. By default every token must appear somewhere in the matched segment (see keyword_match). Wrap any token sequence in double quotes (e.g. "machine learning") to additionally require those words adjacent and in order in the segment's spoken dialogue — a speaker's own name is not indexed as dialogue, so quoting a person's name finds segments where the name appears in what was said, not segments they speak in. Adjacency spans consecutive lines, so a phrase may rarely straddle a line break. Multiple quoted phrases AND together (e.g. "central bank" "interest rates"). There is no boolean OR — a bare OR is treated as an ordinary word, so pass alternatives as separate requests.

Maximum string length: 500

keyword_match · enum<string> · default: required

How unquoted keyword_search terms are applied. 'required' (default) filters to segments containing every term, so results are guaranteed to contain what you typed — this also constrains semantic_search, making a hybrid query an intersection of the two. 'ranked' instead lets unquoted terms only boost BM25 relevance without excluding anything, which widens recall for loose bag-of-words queries but returns segments that may contain none of them. Quoted phrases are unaffected: they filter in BOTH modes, so to relax a phrase remove its quotes. Ignored when keyword_search is empty.

Available options: required, ranked

entity_id · string

Optional entity slug or ID. Filters results to episodes featuring this entity. For 'every line about X', use /v1/podcasts/mentions instead.

entity_type · string

Optional entity category slug. Filters to episodes that mention any entity in that category (e.g. 'company', 'school', 'book'). Speakers are always people, so this filter only narrows mentioned entities. Cannot be combined with 'role'. Ignored when entity_id resolves to a specific entity. See GET /v1/entities/types for the available slugs.

company_id · string

Optional company slug, domain, or ID. Resolves to the company's linked entity and applies as a filter.

episode_id · string

Filter to a specific episode by slug or ID.

podcast_id · string

Podcast slug, internal ID, or numeric iTunes ID.

type · enum<string>

Segment type filter.

Available options: INTRO, PERSONAL_BANTER, TOPIC_DISCUSSION, INTERVIEW, TRANSITION, AD, OUTRO

role · enum<string>

How the entity must relate to the episode. Speaking roles: 'guest', 'host', 'panelist', 'correspondent', or 'speaker' for any of them. 'mention' means the entity is talked about rather than speaking. Omit to match both. Matches the role values on /v1/podcasts/episodes.

Available options: guest, host, panelist, correspondent, speaker, mention

language · string

Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.

Example:

"fr"

since · string

Only segments from episodes published after this date.

Example:

"2024-01-01"

until · string

Only segments from episodes published on or before this date. A bare date includes that whole day.

Example:

"2024-06-01"

sort · enum<string>

Sort order. Defaults to relevance.

Available options: relevance, recency

context · integer<int64> · default: 1

Lines of surrounding dialogue around each matched line (1-15, default 1). Widens each match's transcript window in place — request more context instead of fetching the full transcript. Window size stays bounded even at the maximum.

Required range: 1 <= x <= 15

limit · integer<int64> · default: 25

Results per page (1-100, default 25).

Required range: 1 <= x <= 100

cursor · string

Opaque cursor from a previous response.

Response

200

application/json

OK

data · object[] | null · required

Matches on this page, ranked by relevance (default) or recency

Show child attributes

has_more · boolean · required

More results available

company · object

Resolved company, when company_id filtered the result set. Omitted when only entity_id was provided.

Show child attributes

cursor · string

Opaque cursor; pass back as ?cursor= for the next page

diagnostics · object

Present only when data is empty: which filter excluded everything, why, and the parameter change to retry with.

Show child attributes

entity · object

Resolved entity, when entity_id or company_id filtered the result set

Show child attributes