Skip to main content
GET /v1/podcasts/mentions returns every line of dialogue across the catalog where a resolved entity is named, grouped by episode and ordered by recency. Each item in data is one episode plus all of its mention windows. A mention window is a contiguous range of dialogue around a name, with is_mention flagged on the lines that actually contain it. This is the right endpoint when the answer doesn’t depend on the wording of your query — only on who is being named.
Available to MCP agents as particle_podcast_find_mentions.
You can answer questions like:
  • Every line said about a company this week, newest first, with who said it and in which segment.
  • What one show has been saying about one person over the past year.
  • Where a person was named while appearing as a guest, as opposed to being discussed in their absence.

​
Examples

​
Response

One episode = one item in data. windows[] is ordered by time within the episode. mention_count is the number of lines that triggered is_mention=true. mention_variants is the distinct strings observed for the entity (e.g., ["Sam Altman", "Altman"]) — useful for UI labels. Each is_mention line carries segment_id, the segment containing that line; a window’s segment is the segment where the window opens, which is context_lines before its first mention and can be the previous segment, so cite a mention by its line’s segment_id. If an episode mentions the entity more than 50 times, the page surfaces the first 50 windows and sets truncated: true on the episode. The next-page cursor still advances to a different episode — windows never split across pages.

​
Filters

​
Empty results

An empty data array means no transcribed episode matching your filters names the entity; it is not an error. Three things to check, in order: that the slug is the one GET /v1/entities/search?q= returns for the name, and that the result’s mentions.podcast_episodes is non-zero (a slug that resolves to nothing is rejected with 422 unresolved_reference; a wrong-but-valid one returns someone else’s mentions; a count of zero means no episode carries an entity tag for the subject, so the only lines left to find are the verbatim name matches this endpoint returns, marked matched_by: "name", for a person or company without a linked knowledge-graph entity); whether role, podcast_id, publisher_id, or the date window is doing the narrowing, by dropping them one at a time; and whether the name only comes up in ad reads, which include_ads=true brings back. For “how often, over time” rather than “which lines”, use GET /v1/podcasts/mentions/timeseries, which returns every bucket in the window in one response, up to 1,000 buckets, so pick an interval that fits the window.

​
Pagination

Standard limit (1–100, default 25) + opaque cursor. The unit of pagination is the episode — a single episode never splits across pages, so a page may return fewer total dialogue lines than another with the same limit. Pass the cursor from the previous response back as ?cursor=… for the next page.

​
Which shows, compared with the period before

GET /v1/podcasts/mentions/by-podcast returns the podcasts that mentioned an entity in a window, each with its counts there and in the equal-length window just before it. Use it to see which shows picked a subject up, which kept talking about it, and which went quiet, without paging the mentions themselves. It takes the same subject and filters as the timeseries: entity_id or company_id, plus publisher_id, role, language, include_ads, and the guest_ filters.
  • Windows. since and until set the current window. It defaults to the last 7 days ending now and may span 90. The previous window is as long and ends where the current one starts. The response echoes the exact bounds as start and end: pass them back as since and until when you page, so a default window does not move between pages.
  • Totals. 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. new_podcasts, continuing_podcasts, and dropped_podcasts count the shows in each state.
  • change. new keeps the shows that mentioned the subject in the current window only, continuing those that did in both, and dropped those that did in the previous window only.
  • sort. mentions (the default) puts the most current-window mention lines first, then the shows that dropped the subject, biggest first. rising and falling order by mention_count_delta. popularity puts the biggest shows first.
  • interval. day, week, or month adds each row’s buckets over the current window, with the same shape as the timeseries buckets.
  • The newest day. An episode’s mentions are counted once it is processed, usually within a day of publication, so a window ending now reads slightly low. End it a day earlier for a settled comparison.
To read what a show said, call GET /v1/podcasts/mentions with the row’s podcast as podcast_id and the same since and until. Ad reads are excluded unless include_ads=true, as everywhere on this page.