Search podcast dialogue for entity mentions

Returns every line of dialogue that mentions a person or company, grouped by episode and ordered by recency. Each result is one episode plus all of that episode’s mention windows — a window is a contiguous range of dialogue containing the mention with context_lines of surrounding context, and lines containing the mention have is_mention=true.

Mentions inside ad reads are excluded by default; pass include_ads=true to include them.

Subjects with no knowledge graph entity (most podcast guests, smaller companies) are matched by scanning dialogue for their name verbatim instead of curated entity tags; such pages carry matched_by: "name" and echo the resolved person or company instead of entity.

Use this endpoint for the “every line about X” use case. For finding dialogue by topic or exact phrase use /v1/podcasts/episodes/search instead.

GET /v1/podcasts/mentions

cURL

cURL

curl -H "X-API-Key: $PARTICLE_API_KEY" \
  "https://api.particle.pro/v1/podcasts/mentions?context_lines=2&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>",
        "web_url": "<string>"
      },
      "mention_count": 123,
      "mention_variants": [
        "<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>",
              "segment_id": "<string>"
            }
          ],
          "start_seconds": 123,
          "segment": {
            "id": "<string>",
            "title": "<string>",
            "type": "<string>"
          },
          "url": "<string>"
        }
      ],
      "speakers": [
        {
          "name": "<string>",
          "description": "<string>",
          "descriptor": "<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>"
          },
          "expertise": {
            "standing": "established",
            "fields": [
              {
                "code": "<string>",
                "slug": "<string>",
                "standard": "soc_2018",
                "title": "<string>",
                "group": "minor",
                "level": 123,
                "parent_code": "<string>"
              }
            ],
            "occupations": [
              {
                "code": "<string>",
                "slug": "<string>",
                "standard": "soc_2018",
                "title": "<string>",
                "established": true,
                "group": "minor",
                "level": 123,
                "parent_code": "<string>",
                "practicing": true
              }
            ],
            "seniority": "professional"
          },
          "person": {
            "id": "<string>",
            "name": "<string>",
            "description": "<string>",
            "image_url": "<string>",
            "slug": "<string>"
          },
          "role": "<string>",
          "speaking_duration_seconds": 123
        }
      ],
      "truncated": true
    }
  ],
  "has_more": true,
  "company": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "domain": "<string>",
    "image_url": "<string>",
    "slug": "<string>",
    "ticker": "<string>"
  },
  "cursor": "<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>"
  },
  "matched_by": "<string>",
  "person": {
    "id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "image_url": "<string>",
    "slug": "<string>"
  }
}

Prefer the terminal? This endpoint is also a command in the Particle CLI: pick Particle CLI in the request example’s language menu. Install the Particle CLI.

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

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

Query Parameters

entity_id · string

Entity slug (e.g., 'sam-altman') or ID. A person slug or ID resolves via the person's linked knowledge graph entity; a person with no linked entity falls back to name matching (matched_by=name). Required when company_id is not set.

company_id · string

Company slug, domain, or ID. Required when entity_id is not set. Resolves to the company's linked entity; a company with no linked entity falls back to name matching (matched_by=name).

podcast_id · string

Restrict to mentions inside one podcast.

publisher_id · string

Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID.

episode_id · string

Restrict to mentions inside one episode by slug or ID (cross-corpus result still surfaces a single episode group).

role · enum<string>

Constrain how the entity participates: guest, host, panelist, correspondent, or mention.

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

sort · enum<string>

Result ordering. recency (the default) returns the most recently published episodes first. popularity orders by the parent podcast's global popularity percentile — the biggest shows first, recency breaking ties within a show, non-charting podcasts last. favorites keeps the recency ordering but lifts the calling user's favorited shows to the top of each publication day; it requires an authenticated user session (401 for an API key or anonymous token) and falls back to plain recency for a user with no favorited podcasts. Pass the same sort alongside a cursor when paginating.

Available options: recency, popularity, favorites

include_ads · boolean

Mentions inside ad reads (sponsor ad segments, or lines spoken by an advertiser) are excluded by default. Pass true to include them.

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 episodes published after this date.

Example:

"2024-01-01"

until · string

Only episodes published before this date.

Example:

"2024-06-01"

context_lines · integer<int64> · default: 2

Surrounding dialogue lines around each mention.

Required range: 0 <= x <= 20

limit · integer<int64> · default: 25

Episodes per page (1-100, default 25). Each episode's full set of mention windows is returned in a single page; episodes never split across pages.

Required range: 1 <= x <= 100

cursor · string

Opaque cursor from a previous response.

guest_occupation · string

Only mentions spoken by a guest listed under this SOC 2018 or ISCO-08 occupation (code, slug, or title), including a SOC group or everyday name such as physicians or doctors. A word with no occupation filters by the field of research or capacity it names: oncologists is field 3211, founders is guest_capacity=executive_founder.

Maximum string length: 200

guest_field · string

Only mentions spoken by a guest listed under this ANZSRC 2020 field of research (code, slug, or title).

Maximum string length: 200

guest_standing · enum<string>

Only mentions spoken by a guest whose standing is recognized this way.

Available options: established, self_described, unverified

guest_seniority · enum<string>

Only mentions spoken by a guest at this seniority or above.

Available options: professional, senior, distinguished

guest_capacity · enum<string>

Only mentions spoken by a guest who knows their field in this capacity, such as executive_founder for founders. It narrows the other filters; an everyday word for a capacity passed as guest_occupation (founders, politicians) lands here too.

Available options: researcher, licensed_professional, practitioner, executive_founder, public_official, journalist_analyst, creator_entertainer, athlete_coach, clergy, firsthand, layperson

guest_practicing · boolean

Only mentions spoken by a guest who still works in guest_occupation, a SOC 2018 occupation or group.

guest_in_field · boolean

Only mentions spoken by a guest speaking within their field (the guest the other guest_ filters select, when given).

Response

200

application/json

OK

data · object[] · required

Episodes on this page, ordered by recency (default) or salience

Show child attributes

has_more · boolean · required

More episodes 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

entity · object

Resolved entity. Omitted on empty pages where neither entity_id nor company_id resolved, and on name-matched pages (see matched_by) where the subject has no knowledge graph entity.

Show child attributes

matched_by · string

How mention lines were matched. Omitted for the default knowledge-graph tag matching; 'name' when the subject has no knowledge graph entity and dialogue was scanned for the subject's name verbatim.

person · object

Resolved person, when entity_id resolved to a person with no linked knowledge graph entity (name-match fallback).

Show child attributes