---
title: "List an entity's mentions by podcast"
method: GET
path: "/v1/podcasts/mentions/by-podcast"
tags: ["Podcast Episode Search", "tier:standard"]
---

# List an entity's mentions by podcast

`GET /v1/podcasts/mentions/by-podcast`

## Request

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

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`.

## Query parameters

- `entity_id` string: Entity slug (e.g., 'sam-altman') or ID. 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.
- `publisher_id` string: Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID.
- `role` 'guest' | 'host' | 'panelist' | 'correspondent' | 'mention': Constrain how the entity participates: guest, host, panelist, correspondent, or mention.
- `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'.
- `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).
- `since` string: 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.
- `until` string: End of the current window: a bare date includes that whole UTC day, a date-time is excluded. Defaults to now.
- `change` 'new' | 'continuing' | 'dropped': Only podcasts that are new to the subject (mentioned it in the current window only), continuing (both windows), or dropped (the previous window only).
- `sort` 'mentions' | 'rising' | 'falling' | 'popularity': 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.
- `interval` 'day' | 'week' | 'month': Add each podcast's counts per bucket of this width over the current window.
- `limit` integer: Results per page
- `cursor` string: Opaque pagination cursor from previous response

## Response `200`

OK

- MentionPodcasts
  - `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.
  - `continuing_podcasts` integer, required: Podcasts that mentioned it in both windows
  - `cursor` string: Pass to next request for more results
  - `data` MentionPodcast[], nullable, required: List of results
    - `buckets` MentionTimeseriesBucket[], nullable: Its counts per bucket over the current window, when interval is set: contiguous, zero-filled, and in ascending order.
      - `episode_count` integer, required: Episodes with at least one counted mention in this bucket
      - `mention_count` integer, required: Counted mention lines in this bucket
      - `partial` boolean: 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.
      - `podcast_count` integer, required: Distinct podcasts those episodes aired on: how many shows carried the subject in this bucket
      - `start` string, required: Bucket start as a UTC date
    - `change` 'new' | 'continuing' | 'dropped', required: new: mentioned in the current window only; continuing: in both; dropped: in the previous window only
    - `episode_count` integer, required: Its episodes with at least one counted mention in the current window
    - `last_mention_at` string, date-time: Publication time of its latest current-window episode mentioning the subject. Omitted when it dropped the subject.
    - `mention_count` integer, required: Counted mention lines across those episodes
    - `mention_count_delta` integer, required: mention_count minus previous_mention_count
    - `podcast` PodcastCompact, required
      - `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
    - `previous_episode_count` integer, required: Its episodes with at least one counted mention in the previous window
    - `previous_mention_count` integer, required: Counted mention lines across those episodes
  - `distinct_podcasts` integer, required: Podcasts with at least one of those episodes
  - `dropped_podcasts` integer, required: Podcasts that mentioned it in the previous window but not the current one
  - `end` string, date-time, required: End of the current window, excluded.
  - `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: Whether more results exist
  - `new_podcasts` integer, required: Podcasts that mentioned the subject in the current window but not the previous one
  - `previous_distinct_podcasts` integer, required: Podcasts with at least one of those episodes
  - `previous_start` string, date-time, required: Start of the previous window, included. The previous window is as long as the current one and ends where it starts.
  - `previous_total_episodes` integer, required: Episodes with at least one counted mention in the previous window
  - `previous_total_mentions` integer, required: Counted mention lines across those episodes
  - `start` string, date-time, required: Start of the current window, included. Pass it back as since, with end as until, to page or re-read the same windows.
  - `total_episodes` integer, required: Episodes with at least one counted mention in the current window, across every podcast
  - `total_mentions` integer, required: Counted mention lines across those episodes

## 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

## Changes

- **2026-10-19** `416ba82ab9d7`: 1 info
  - added the non-success response with the status `402`

[Operation history](https://skmtc.dev/particle/apis/particle-api/changes/v1/podcasts/mentions/by-podcast/get.md)

---

[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)