> ## 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. # 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. ## OpenAPI ````yaml /openapi.json get /v1/podcasts/mentions openapi: 3.1.0 info: description: Public API for Particle — news intelligence, financial data, and analysis. title: Particle API version: 0.1.0 servers: - url: https://api.particle.pro security: - ApiKeyHeader: [] - BearerAuth: [] paths: /v1/podcasts/mentions: get: tags: - Podcast Episode Search - tier:standard summary: Search podcast dialogue for entity mentions description: >- 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. operationId: search-podcast-mentions parameters: - description: >- 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. explode: false in: query name: entity_id schema: description: >- 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. type: string - description: >- 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). explode: false in: query name: company_id schema: description: >- 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). type: string - description: Restrict to mentions inside one podcast. explode: false in: query name: podcast_id schema: description: Restrict to mentions inside one podcast. type: string - description: >- Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID. explode: false in: query name: publisher_id schema: description: >- Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID. type: string - description: >- Restrict to mentions inside one episode by slug or ID (cross-corpus result still surfaces a single episode group). explode: false in: query name: episode_id schema: description: >- Restrict to mentions inside one episode by slug or ID (cross-corpus result still surfaces a single episode group). type: string - description: >- Constrain how the entity participates: guest, host, panelist, correspondent, or mention. explode: false in: query name: role schema: description: >- Constrain how the entity participates: guest, host, panelist, correspondent, or mention. enum: - guest - host - panelist - correspondent - mention type: string - description: >- 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. Pass the same sort alongside a cursor when paginating. explode: false in: query name: sort schema: description: >- 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. Pass the same sort alongside a cursor when paginating. enum: - recency - popularity type: string - description: >- Mentions inside ad reads (sponsor ad segments, or lines spoken by an advertiser) are excluded by default. Pass true to include them. explode: false in: query name: include_ads schema: description: >- Mentions inside ad reads (sponsor ad segments, or lines spoken by an advertiser) are excluded by default. Pass true to include them. type: boolean - description: Only episodes published after this date. explode: false in: query name: since schema: description: Only episodes published after this date. examples: - '2024-01-01' type: string - description: Only episodes published before this date. explode: false in: query name: until schema: description: Only episodes published before this date. examples: - '2024-06-01' type: string - description: Surrounding dialogue lines around each mention. explode: false in: query name: context_lines schema: default: 2 description: Surrounding dialogue lines around each mention. format: int64 maximum: 20 minimum: 0 type: integer - description: >- 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. explode: false in: query name: limit schema: default: 25 description: >- 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. format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque cursor from a previous response. explode: false in: query name: cursor schema: description: Opaque cursor from a previous response. type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/PodcastMentionsPage' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/PlatformError' description: Error x-codeSamples: - label: cURL lang: curl source: |- curl -H "X-API-Key: $PARTICLE_API_KEY" \ "https://api.particle.pro/v1/podcasts/mentions?context_lines=2&limit=25" components: schemas: PodcastMentionsPage: additionalProperties: false properties: company: $ref: '#/components/schemas/CompanyCompact' description: >- Resolved company, when company_id filtered the result set. Omitted when only entity_id was provided. cursor: description: Opaque cursor; pass back as ?cursor= for the next page type: string data: description: Episodes on this page, ordered by recency (default) or salience items: $ref: '#/components/schemas/PodcastMentionEpisode' type: - array - 'null' entity: $ref: '#/components/schemas/EntityCompact' description: >- 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. has_more: description: More episodes available type: boolean matched_by: description: >- 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. type: string person: $ref: '#/components/schemas/PersonCompact' description: >- Resolved person, when entity_id resolved to a person with no linked knowledge graph entity (name-match fallback). required: - data - has_more type: object PlatformError: additionalProperties: false properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string error_code: type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string resolve: $ref: '#/components/schemas/ErrorResolve' status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object CompanyCompact: additionalProperties: false properties: description: description: Short company description, when known. type: string domain: description: Primary website domain (e.g. 'nvidia.com'), when known. type: string id: description: Company identifier (domain, slug, or encoded ID) type: string image_url: description: Company logo or image URL type: string name: description: Company name type: string slug: description: >- 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. type: string ticker: description: Primary stock ticker symbol, when listed. type: string required: - id - name type: object PodcastMentionEpisode: additionalProperties: false properties: episode: $ref: '#/components/schemas/EpisodeCompactWithPodcast' description: Episode containing the mentions mention_count: description: Number of dialogue lines containing the entity in this episode format: int64 type: integer mention_variants: description: Distinct mention strings observed (e.g. ["Sam Altman", "Altman"]) items: type: string type: - array - 'null' truncated: description: >- True when the episode had more mention windows than fit in the response type: boolean windows: description: Mention windows ordered by time items: $ref: '#/components/schemas/PodcastMentionWindow' type: - array - 'null' required: - episode - mention_count - mention_variants - windows type: object EntityCompact: additionalProperties: false properties: company: $ref: '#/components/schemas/EntityCompany' description: Linked company record, if this entity is a known company description: description: Short description type: string id: description: Entity ID type: string image_url: description: Entity image URL type: string name: description: Entity name type: string person: $ref: '#/components/schemas/EntityPerson' description: Linked person record, if this entity is a known person slug: description: Human-readable slug identifier type: string type: $ref: '#/components/schemas/EntityType' description: Category. Omitted when the entity falls outside the supported set. wikipedia_url: description: Wikipedia URL type: string required: - id - slug - name type: object PersonCompact: additionalProperties: false properties: description: description: Short description (e.g. current role), when known. type: string id: description: Encoded Person identifier type: string image_url: description: Canonical headshot URL when one is known for the Person type: string name: description: Display name type: string slug: description: >- Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface. type: string required: - id - name type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object ErrorResolve: additionalProperties: false properties: action: type: string endpoint: type: string message: type: string method: type: string url: type: string required: - message type: object EpisodeCompactWithPodcast: additionalProperties: false properties: id: description: Episode ID type: string podcast: $ref: '#/components/schemas/PodcastCompact' description: Parent podcast published_at: description: Publication date format: date-time type: string slug: description: Human-readable slug identifier type: string title: description: Episode title type: string required: - id - title type: object PodcastMentionWindow: additionalProperties: false properties: end_seconds: description: Window end time in seconds (episode-absolute) format: double type: number lines: description: >- Dialogue lines in this window. Lines containing the mention have is_mention=true. items: $ref: '#/components/schemas/TranscriptLine' type: - array - 'null' segment: $ref: '#/components/schemas/SegmentCompact' description: Segment containing the mention. Nil when no segment overlaps. start_seconds: description: Window start time in seconds (episode-absolute) format: double type: number required: - start_seconds - end_seconds - lines type: object EntityCompany: additionalProperties: false properties: domain: description: Company website domain type: string id: description: Company identifier type: string ticker: description: Primary stock ticker symbol type: string required: - id type: object EntityPerson: additionalProperties: false properties: company: description: Current company name type: string id: description: Person identifier type: string image_url: description: Person headshot URL type: string title: description: Current role title type: string required: - id type: object EntityType: additionalProperties: false properties: name: description: Human-friendly display label (e.g. 'Company'). type: string slug: description: >- Stable identifier, safe to pass to the type query parameter (e.g. 'company'). type: string required: - slug - name type: object PodcastCompact: additionalProperties: false properties: id: description: Podcast ID type: string image_url: description: Cover image URL type: string publisher: $ref: '#/components/schemas/PodcastPublisherCompact' description: >- Publisher (network) attributed to this podcast. Present only when the embedding endpoint preloads publisher attribution and the podcast's publisher is known. slug: description: Human-readable slug identifier type: string title: description: Podcast title type: string required: - id - title type: object TranscriptLine: additionalProperties: false properties: end_seconds: description: End time in seconds (episode-absolute) format: double type: number is_match: description: >- Top-scored line within the window for the current query, on /v1/podcasts/episodes/search results. Not set on /v1/podcasts/mentions. type: boolean is_mention: description: >- 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. type: boolean matched_terms: description: >- 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. items: type: string type: - array - 'null' number: description: Line number within the episode (1-indexed) format: int64 type: integer role: description: Speaker role (HOST, GUEST, etc.) type: string speaker: description: Speaker name or label type: string start_seconds: description: Start time in seconds (episode-absolute) format: double type: number text: description: Spoken text type: string required: - number - speaker - start_seconds - end_seconds - text type: object SegmentCompact: additionalProperties: false properties: id: description: Segment ID type: string title: description: Segment title type: string type: description: Segment type type: string required: - id - type - title type: object PodcastPublisherCompact: additionalProperties: false properties: id: description: Publisher ID type: string name: description: Publisher name type: string slug: description: >- 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). type: string required: - id - name type: object securitySchemes: ApiKeyHeader: description: Pass your API key in the X-API-Key header (recommended). in: header name: X-API-Key type: apiKey BearerAuth: description: Pass your API key as a Bearer token in the Authorization header. scheme: bearer type: http ````