---
title: "Search podcast dialogue for entity mentions"
method: GET
path: "/v1/podcasts/mentions"
tags: ["Podcast Episode Search", "tier:standard"]
---

# Search podcast dialogue for entity mentions

`GET /v1/podcasts/mentions`

## Request

- Base URL: `https://api.particle.pro`
- URL: `https://api.particle.pro/v1/podcasts/mentions`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

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.

## 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` 'guest' | 'host' | 'panelist' | 'correspondent' | 'mention': Constrain how the entity participates: guest, host, panelist, correspondent, or mention.
- `sort` 'recency' | 'popularity' | 'favorites': 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.
- `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'.
- `since` string: Only episodes published after this date.
- `until` string: Only episodes published before this date.
- `context_lines` integer: Surrounding dialogue lines around each mention.
- `limit` integer: 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.
- `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.
- `guest_field` string: Only mentions spoken by a guest listed under this ANZSRC 2020 field of research (code, slug, or title).
- `guest_standing` 'established' | 'self_described' | 'unverified': Only mentions spoken by a guest whose standing is recognized this way.
- `guest_seniority` 'professional' | 'senior' | 'distinguished': Only mentions spoken by a guest at this seniority or above.
- `guest_capacity` 'researcher' | 'licensed_professional' | 'practitioner' | 'executive_founder' | 'public_official' | 'journalist_analyst' | 'creator_entertainer' | 'athlete_coach' | 'clergy' | 'firsthand' | 'layperson': 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.
- `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`

OK

- PodcastMentionsPage
  - `company` CompanyCompact
    - `description` string: Short company description, when known.
    - `domain` string: Primary website domain (e.g. 'nvidia.com'), when known.
    - `id` string, required: Company identifier (domain, slug, or encoded ID)
    - `image_url` string: Company logo or image URL
    - `name` string, required: Company name
    - `slug` string: Stable human-readable handle (the linked knowledge-graph slug, e.g. 'nvidia'), when known. Companies have no slug of their own; prefer this for display and pass it (or id) to /v1/companies.
    - `ticker` string: Primary stock ticker symbol, when listed.
  - `cursor` string: Opaque cursor; pass back as ?cursor= for the next page
  - `data` PodcastMentionEpisode[], nullable, required: Episodes on this page, ordered by recency (default) or salience
    - `episode` EpisodeCompactWithPodcast, required
      - `id` string, required: Episode ID
      - `podcast` PodcastCompact
        - `best_rank` PodcastRankingHandle
          - `captured_at` string, date-time, required
          - `category_slug` string
          - `chart_type` 'top_podcasts', required
          - `country` string
          - `rank` integer, required
          - `source` 'apple' | 'spotify', required
        - `id` string, required: Podcast ID
        - `image_url` string: Cover image URL
        - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints.
        - `publisher` PodcastPublisherCompact
          - `id` string, required: Publisher ID
          - `name` string, required: Publisher name
          - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs).
        - `slug` string: Human-readable slug identifier
        - `title` string, required: Podcast title
      - `published_at` string, date-time: Publication date
      - `slug` string: Human-readable slug identifier
      - `title` string, required: Episode title
      - `web_url` string: The episode's page on Radar, where it plays beside its transcript: https://radar.particle.pro/podcasts/{podcast}/episodes/{episode}, each segment the slug or, when there is none, the raw UUID. Append ?t={seconds} to start at a moment; the hit's own url field already does. Omitted for back-catalogue episodes we have not ingested, which have no page, and in episode stream, feed and archive payloads stored before this field shipped (they are replayed as stored): build it from the slugs, or fetch the episode.
    - `mention_count` integer, required: Number of dialogue lines containing the entity in this episode
    - `mention_variants` string[], nullable, required: Distinct mention strings observed (e.g. ["Sam Altman", "Altman"])
    - `speakers` EpisodeSpeaker[], nullable: The identified people speaking in the windows' lines, in order of first line, each with their expertise; a line's speaker matches an entry by name. Omitted when no speaker is identified.
      - `description` string: Brief description of the speaker
      - `descriptor` string: Movie-credits-style role-in-context label for speakers we can describe but not identify by name ("Taylor's Lawyer", "Court Officer"). Co-exists with name carrying the raw STT label when no identity could be established. Rendered by clients when descriptor is non-empty and the speaker is otherwise unresolved.
      - `entity` EntityCompact
        - `company` EntityCompany
          - `domain` string: Company website domain
          - `id` string, required: Company identifier
          - `ticker` string: Primary stock ticker symbol
        - `description` string: Short description
        - `id` string, required: Entity ID
        - `image_url` string: Entity image URL
        - `name` string, required: Entity name
        - `person` EntityPerson
          - `company` string: Current company name
          - `id` string, required: Person identifier
          - `image_url` string: Person headshot URL
          - `title` string: Current role title
        - `slug` string, required: Human-readable slug identifier
        - `type` EntityType
          - `name` string, required: Human-friendly display label (e.g. 'Company').
          - `slug` string, required: Stable identifier, safe to pass to the type query parameter (e.g. 'company').
        - `wikipedia_url` string: Wikipedia URL
      - `expertise` SpeakerExpertise
        - `fields` ExpertiseCode[], nullable: Up to three ANZSRC 2020 fields of research the speaker is listed under, most specific first, none an ancestor of another. Pass a code or slug as guest_field (or field) to filter by it.
          - `code` string, required: The standard's own notation, such as 29-1212 (SOC), 2212 (ISCO), or 320101 (FoR).
          - `group` 'minor' | 'broad' | 'alias': Set for a code that stands for several detailed SOC 2018 occupations: a SOC minor group (such as 29-1000 Healthcare Diagnosing or Treating Practitioners), a broad group (such as 29-1210 Physicians), or an alias, an everyday name such as doctors (physicians and surgeons). Every occupation filter accepts one and matches a speaker listed under any of its occupations.
          - `level` integer: Depth in the standard's official hierarchy: SOC major group 1 and detailed occupation 2; FoR division 1, group 2, field 3; ISCO-08 unit group 4 and minor group 3. ISCO-08 codes are the groups SOC maps to, listed flat without the standard's upper levels. Omitted for a SOC group or alias (see group).
          - `parent_code` string: The standard's official parent code; omitted at the top level and for every ISCO-08 code, since ISCO-08 is listed without its upper levels. A SOC broad group's parent is its minor group and a minor group's its major group, but a detailed SOC occupation's official parent is its major group (29-1211 has parent_code 29-0000), so it can differ from parent, which is the browse parent one level up (29-1210).
          - `slug` string, required: The title as a URL segment, such as cardiologists.
          - `standard` 'soc_2018' | 'isco_08' | 'anzsrc_for_2020', required: The standard the code belongs to: soc_2018 (US Standard Occupational Classification), isco_08 (the ILO's International Standard Classification of Occupations), or anzsrc_for_2020 (ANZSRC Fields of Research).
          - `title` string, required: The standard's official title, such as Cardiologists.
        - `occupations` PersonOccupation[], nullable: Up to three SOC 2018 occupations the speaker is listed under, most specific first, none an ancestor of another. Pass a code or slug as guest_occupation (or occupation) to filter by it.
          - `code` string, required: The standard's own notation, such as 29-1212 (SOC), 2212 (ISCO), or 320101 (FoR).
          - `established` boolean: Whether others conferred the speaker's standing in this occupation, such as a licence or an appointment, rather than the speaker describing it. Present for detailed SOC 2018 occupations only.
          - `group` 'minor' | 'broad' | 'alias': Set for a code that stands for several detailed SOC 2018 occupations: a SOC minor group (such as 29-1000 Healthcare Diagnosing or Treating Practitioners), a broad group (such as 29-1210 Physicians), or an alias, an everyday name such as doctors (physicians and surgeons). Every occupation filter accepts one and matches a speaker listed under any of its occupations.
          - `level` integer: Depth in the standard's official hierarchy: SOC major group 1 and detailed occupation 2; FoR division 1, group 2, field 3; ISCO-08 unit group 4 and minor group 3. ISCO-08 codes are the groups SOC maps to, listed flat without the standard's upper levels. Omitted for a SOC group or alias (see group).
          - `parent_code` string: The standard's official parent code; omitted at the top level and for every ISCO-08 code, since ISCO-08 is listed without its upper levels. A SOC broad group's parent is its minor group and a minor group's its major group, but a detailed SOC occupation's official parent is its major group (29-1211 has parent_code 29-0000), so it can differ from parent, which is the browse parent one level up (29-1210).
          - `practicing` boolean: Whether the speaker still works in this occupation, as opposed to having worked in it. Present for detailed SOC 2018 occupations only.
          - `slug` string, required: The title as a URL segment, such as cardiologists.
          - `standard` 'soc_2018' | 'isco_08' | 'anzsrc_for_2020', required: The standard the code belongs to: soc_2018 (US Standard Occupational Classification), isco_08 (the ILO's International Standard Classification of Occupations), or anzsrc_for_2020 (ANZSRC Fields of Research).
          - `title` string, required: The standard's official title, such as Cardiologists.
        - `seniority` 'professional' | 'senior' | 'distinguished': The highest level the speaker has reached in their field; omitted below professional.
        - `standing` 'established' | 'self_described' | 'unverified', required: How the speaker's standing is recognized: established (conferred by others: a credential, a position, recognition in the field), self_described (claimed by the speaker), or unverified (the records do not say, which never means the speaker is not an expert).
      - `name` string, required: Speaker name
      - `person` PersonCompact
        - `description` string: Short description (e.g. current role), when known.
        - `id` string, required: Encoded Person identifier
        - `image_url` string: Canonical headshot URL when one is known for the Person
        - `name` string, required: Display name
        - `slug` string: Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface.
      - `role` string: Speaker role, always one of HOST, GUEST, PANELIST, CORRESPONDENT, MODERATOR, NARRATOR, ANNOUNCER, VOICE_ACTOR, SOUNDBITE_SPEAKER, AUDIENCE, ADVERTISER, PRODUCER, UNKNOWN, OTHER. Responses carry only HOST, GUEST, PANELIST and CORRESPONDENT unless you widen the set with the role query param.
      - `speaking_duration_seconds` number, double: Total speaking time in seconds
    - `truncated` boolean: True when the episode had more mention windows than fit in the response
    - `windows` PodcastMentionWindow[], nullable, required: Mention windows ordered by time
      - `end_seconds` number, double, required: Window end time in seconds (episode-absolute)
      - `lines` TranscriptLine[], nullable, required: Dialogue lines in this window. Lines containing the mention have is_mention=true.
        - `end_seconds` number, double, required: End time in seconds (episode-absolute)
        - `is_match` boolean: Top-scored line within the window for the current query, on /v1/podcasts/episodes/search results. Not set on /v1/podcasts/mentions.
        - `is_mention` boolean: Line contains a textual mention of the resolved entity. Set on /v1/podcasts/mentions only — /v1/podcasts/episodes/search treats entity_id as a filter and does not mark mention lines.
        - `matched_terms` string[], nullable: Terms from the query that occur in this line, longest-first, for clients to highlight. Locate them case-insensitively: each term is spelled as the query spelled it, which may differ in case from the line's text (query "openai" is reported for a line reading "OpenAI"). Whole-token matches only — a term never matches inside a longer word, so "AI" is not reported for "said". A multi-word query yields the whole phrase ("founder mode") when it occurs contiguously, so clients mark it as one span rather than highlighting each word separately; individual words appear only where they occur outside the phrase. Only the longest term is reported at any position, so terms never overlap. On /v1/podcasts/episodes/search this is set on any line in the window containing the query, not only is_match lines; on /v1/podcasts/mentions it is set only on is_mention lines. Absent when nothing matched or the query was not text-based.
        - `number` integer, required: Line number within the episode (1-indexed)
        - `role` string: Speaker role (HOST, GUEST, etc.)
        - `segment_id` string: The segment containing this line. Set on is_mention lines of /v1/podcasts/mentions, so a mention can be cited by segment even when its window opened in the previous one (a window starts context_lines before its first mention, and the window's segment is where the window starts). Absent elsewhere.
        - `speaker` string, required: Speaker name or label
        - `start_seconds` number, double, required: Start time in seconds (episode-absolute)
        - `text` string, required: Spoken text
      - `segment` SegmentCompact
        - `id` string, required: Segment ID
        - `title` string, required: Segment title
        - `type` string, required: Segment type
      - `start_seconds` number, double, required: Window start time in seconds (episode-absolute)
      - `url` string: Moment link that plays this window on Radar: the episode's web_url with ?t= at start_seconds. Cite or share it to link the exact mention.
  - `entity` EntityCompact
    - `company` EntityCompany
      - `domain` string: Company website domain
      - `id` string, required: Company identifier
      - `ticker` string: Primary stock ticker symbol
    - `description` string: Short description
    - `id` string, required: Entity ID
    - `image_url` string: Entity image URL
    - `name` string, required: Entity name
    - `person` EntityPerson
      - `company` string: Current company name
      - `id` string, required: Person identifier
      - `image_url` string: Person headshot URL
      - `title` string: Current role title
    - `slug` string, required: Human-readable slug identifier
    - `type` EntityType
      - `name` string, required: Human-friendly display label (e.g. 'Company').
      - `slug` string, required: Stable identifier, safe to pass to the type query parameter (e.g. 'company').
    - `wikipedia_url` string: Wikipedia URL
  - `has_more` boolean, required: More episodes available
  - `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` PersonCompact
    - `description` string: Short description (e.g. current role), when known.
    - `id` string, required: Encoded Person identifier
    - `image_url` string: Canonical headshot URL when one is known for the Person
    - `name` string, required: Display name
    - `slug` string: Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface.

## Other responses

- `402`: Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent.
- `default`: Error

---

[API](https://skmtc.dev/particle/apis/particle-api.md) · [All operations](https://skmtc.dev/particle/apis/particle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/particle/apis/particle-api/revisions/416ba82ab9d7?raw)