> ## 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. # List an entity's mentions by podcast > Returns the podcasts that mentioned a person, company, or entity in a window, each with its episode and mention line counts there and in the equal-length window just before it, labeled `new`, `continuing`, or `dropped`: which shows picked the subject up, which kept talking about it, and which went quiet, without paging the mentions themselves. The totals count every podcast, whatever the page or `change` filter, and the current window's match `/v1/podcasts/mentions/timeseries` for the same filters. Mentions inside ad reads are excluded unless `include_ads=true`. The window defaults to the last 7 days and may span 90; the response echoes its exact bounds, so pass `start` and `end` back as since and until when paging. The newest day fills in as episodes are processed, usually within a day, so end the window earlier for a settled comparison. `interval` adds each podcast's buckets over the current window. Requires entity_id or company_id. For the lines, call `/v1/podcasts/mentions` with the row's `podcast_id` and the same since and until. For the total over time, use `/v1/podcasts/mentions/timeseries`. ## OpenAPI ````yaml /openapi.json get /v1/podcasts/mentions/by-podcast openapi: 3.1.0 info: contact: email: api@particle.pro name: Particle url: https://particle.pro description: >- Podcast API for transcripts, mentions and sponsorship data. 140,000+ podcasts transcribed, diarized and speaker-identified within minutes of airing, about 28,000 episodes a day. Search transcripts by keyword or meaning, track brand and company mentions with alerts, pull sponsor and ad-read data and rankings. REST API plus an MCP server for AI agents. Also company, people and topic intelligence. summary: >- Podcast API: transcripts, mentions, sponsors and rankings for 140,000+ podcasts. termsOfService: https://particle.pro/legal/tos-api title: Particle API version: 0.1.0 x-guidance: >- Podcast, people, company and topic intelligence. Authenticate with a pp_ API key (X-API-Key header) or pay per request with x402: a keyless call to a billable endpoint returns 402 with the payment requirements in the PAYMENT-REQUIRED header; sign the USDC transfer and repeat the request with PAYMENT-SIGNATURE. Start with GET /v1/podcasts/search?q=; the slugs in responses are the inputs to the other endpoints. Docs: https://docs.particle.pro; setup playbook: https://api.particle.pro/agents.md; endpoint and tool map with prices: https://api.particle.pro/llms.txt; credential recipe: https://api.particle.pro/auth.md. x-logo: url: https://particle.pro/favicon.svg servers: - url: https://api.particle.pro security: - ApiKeyHeader: [] - BearerAuth: [] externalDocs: url: https://docs.particle.pro paths: /v1/podcasts/mentions/by-podcast: get: tags: - Podcast Episode Search - tier:standard summary: List an entity's mentions by podcast description: >- Returns the podcasts that mentioned a person, company, or entity in a window, each with its episode and mention line counts there and in the equal-length window just before it, labeled `new`, `continuing`, or `dropped`: which shows picked the subject up, which kept talking about it, and which went quiet, without paging the mentions themselves. The totals count every podcast, whatever the page or `change` filter, and the current window's match `/v1/podcasts/mentions/timeseries` for the same filters. Mentions inside ad reads are excluded unless `include_ads=true`. The window defaults to the last 7 days and may span 90; the response echoes its exact bounds, so pass `start` and `end` back as since and until when paging. The newest day fills in as episodes are processed, usually within a day, so end the window earlier for a settled comparison. `interval` adds each podcast's buckets over the current window. Requires entity_id or company_id. For the lines, call `/v1/podcasts/mentions` with the row's `podcast_id` and the same since and until. For the total over time, use `/v1/podcasts/mentions/timeseries`. operationId: list-mentions-by-podcast parameters: - description: >- Entity slug (e.g., 'sam-altman') or ID. Required when company_id is not set. explode: false in: query name: entity_id schema: description: >- Entity slug (e.g., 'sam-altman') or ID. 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. 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. 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: >- 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: >- 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: >- 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'. explode: false in: query name: language schema: description: >- 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'. examples: - fr type: string - description: >- 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. explode: false in: query name: guest_occupation schema: description: >- 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. maxLength: 200 type: string - description: >- Only mentions spoken by a guest listed under this ANZSRC 2020 field of research (code, slug, or title). explode: false in: query name: guest_field schema: description: >- Only mentions spoken by a guest listed under this ANZSRC 2020 field of research (code, slug, or title). maxLength: 200 type: string - description: >- Only mentions spoken by a guest whose standing is recognized this way. explode: false in: query name: guest_standing schema: description: >- Only mentions spoken by a guest whose standing is recognized this way. enum: - established - self_described - unverified type: string - description: Only mentions spoken by a guest at this seniority or above. explode: false in: query name: guest_seniority schema: description: Only mentions spoken by a guest at this seniority or above. enum: - professional - senior - distinguished type: string - description: >- 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. explode: false in: query name: guest_capacity schema: description: >- 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. enum: - researcher - licensed_professional - practitioner - executive_founder - public_official - journalist_analyst - creator_entertainer - athlete_coach - clergy - firsthand - layperson type: string - description: >- Only mentions spoken by a guest who still works in guest_occupation, a SOC 2018 occupation or group. explode: false in: query name: guest_practicing schema: description: >- Only mentions spoken by a guest who still works in guest_occupation, a SOC 2018 occupation or group. type: boolean - description: >- Only mentions spoken by a guest speaking within their field (the guest the other guest_ filters select, when given). explode: false in: query name: guest_in_field schema: description: >- Only mentions spoken by a guest speaking within their field (the guest the other guest_ filters select, when given). type: boolean - description: >- Start of the current window, included. Defaults to 7 days before until; the window may span at most 90 days. The previous window is as long and ends where this one starts. explode: false in: query name: since schema: description: >- Start of the current window, included. Defaults to 7 days before until; the window may span at most 90 days. The previous window is as long and ends where this one starts. examples: - '2026-10-01' type: string - description: >- End of the current window: a bare date includes that whole UTC day, a date-time is excluded. Defaults to now. explode: false in: query name: until schema: description: >- End of the current window: a bare date includes that whole UTC day, a date-time is excluded. Defaults to now. examples: - '2026-10-08' type: string - description: >- Only podcasts that are new to the subject (mentioned it in the current window only), continuing (both windows), or dropped (the previous window only). explode: false in: query name: change schema: description: >- Only podcasts that are new to the subject (mentioned it in the current window only), continuing (both windows), or dropped (the previous window only). enum: - new - continuing - dropped type: string - description: >- mentions (the default) puts the most current-window mention lines first, then, for podcasts that dropped the subject, the most previous-window ones. rising and falling order by mention_count_delta, largest gain or largest loss first. popularity orders by the podcast's global popularity percentile, non-charting podcasts last. Pass the same sort alongside a cursor when paging. explode: false in: query name: sort schema: default: mentions description: >- mentions (the default) puts the most current-window mention lines first, then, for podcasts that dropped the subject, the most previous-window ones. rising and falling order by mention_count_delta, largest gain or largest loss first. popularity orders by the podcast's global popularity percentile, non-charting podcasts last. Pass the same sort alongside a cursor when paging. enum: - mentions - rising - falling - popularity type: string - description: >- Add each podcast's counts per bucket of this width over the current window. explode: false in: query name: interval schema: description: >- Add each podcast's counts per bucket of this width over the current window. enum: - day - week - month type: string - description: Results per page explode: false in: query name: limit schema: default: 25 description: Results per page format: int64 maximum: 100 minimum: 1 type: integer - description: Opaque pagination cursor from previous response explode: false in: query name: cursor schema: description: Opaque pagination cursor from previous response type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/MentionPodcasts' 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/by-podcast?sort=mentions&limit=25" components: schemas: MentionPodcasts: additionalProperties: false properties: company: $ref: '#/components/schemas/CompanyCompact' description: The resolved company, when company_id was used continuing_podcasts: description: Podcasts that mentioned it in both windows format: int64 type: integer cursor: description: Pass to next request for more results type: string data: description: List of results items: $ref: '#/components/schemas/MentionPodcast' type: - array - 'null' distinct_podcasts: description: Podcasts with at least one of those episodes format: int64 type: integer dropped_podcasts: description: >- Podcasts that mentioned it in the previous window but not the current one format: int64 type: integer end: description: End of the current window, excluded. format: date-time type: string entity: $ref: '#/components/schemas/EntityCompact' description: The resolved entity the counts are for has_more: description: Whether more results exist type: boolean new_podcasts: description: >- Podcasts that mentioned the subject in the current window but not the previous one format: int64 type: integer previous_distinct_podcasts: description: Podcasts with at least one of those episodes format: int64 type: integer previous_start: description: >- Start of the previous window, included. The previous window is as long as the current one and ends where it starts. format: date-time type: string previous_total_episodes: description: Episodes with at least one counted mention in the previous window format: int64 type: integer previous_total_mentions: description: Counted mention lines across those episodes format: int64 type: integer start: description: >- Start of the current window, included. Pass it back as since, with end as until, to page or re-read the same windows. format: date-time type: string total_episodes: description: >- Episodes with at least one counted mention in the current window, across every podcast format: int64 type: integer total_mentions: description: Counted mention lines across those episodes format: int64 type: integer required: - start - end - previous_start - total_episodes - total_mentions - distinct_podcasts - previous_total_episodes - previous_total_mentions - previous_distinct_podcasts - new_podcasts - continuing_podcasts - dropped_podcasts - 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 MentionPodcast: additionalProperties: false properties: buckets: description: >- Its counts per bucket over the current window, when interval is set: contiguous, zero-filled, and in ascending order. items: $ref: '#/components/schemas/MentionTimeseriesBucket' type: - array - 'null' change: description: >- new: mentioned in the current window only; continuing: in both; dropped: in the previous window only enum: - new - continuing - dropped type: string episode_count: description: Its episodes with at least one counted mention in the current window format: int64 type: integer last_mention_at: description: >- Publication time of its latest current-window episode mentioning the subject. Omitted when it dropped the subject. format: date-time type: string mention_count: description: Counted mention lines across those episodes format: int64 type: integer mention_count_delta: description: mention_count minus previous_mention_count format: int64 type: integer podcast: $ref: '#/components/schemas/PodcastCompact' description: The podcast previous_episode_count: description: >- Its episodes with at least one counted mention in the previous window format: int64 type: integer previous_mention_count: description: Counted mention lines across those episodes format: int64 type: integer required: - podcast - episode_count - mention_count - previous_episode_count - previous_mention_count - mention_count_delta - change 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 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 MentionTimeseriesBucket: additionalProperties: false properties: episode_count: description: Episodes with at least one counted mention in this bucket format: int64 type: integer mention_count: description: Counted mention lines in this bucket format: int64 type: integer partial: description: >- True when the window cuts through this bucket, so it covers less than a full interval: the first bucket when since falls inside it, and the last when until does, as it does for a window that runs to now. Compare full buckets with each other. type: boolean podcast_count: description: >- Distinct podcasts those episodes aired on: how many shows carried the subject in this bucket format: int64 type: integer start: description: Bucket start as a UTC date type: string required: - start - episode_count - mention_count - podcast_count type: object PodcastCompact: additionalProperties: false properties: best_rank: $ref: '#/components/schemas/PodcastRankingHandle' description: >- The single best (lowest-numbered) chart position this podcast currently holds across all charts. Omitted when the podcast holds no current chart appearances, and on endpoints that do not attach it. Reading a full chart (with country/category/source filters and history) remains premium; a single show's own placement is available on every plan. id: description: Podcast ID type: string image_url: description: Cover image URL type: string popularity: description: >- 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. format: double type: number 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 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 PodcastRankingHandle: additionalProperties: false properties: captured_at: format: date-time type: string category_slug: type: string chart_type: enum: - top_podcasts type: string country: type: string rank: format: int64 type: integer source: enum: - apple - spotify type: string required: - source - chart_type - rank - captured_at 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.