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

# Mentions

> Every line of dialogue where a person or company is named, grouped by episode. The right endpoint for read-everything-about-X workflows.

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

<Note>Available to MCP agents as [`particle_podcast_find_mentions`](/mcp/tools/podcasts/podcast-find-mentions).</Note>

## When to use Mentions vs Search

| You want…                                                         | Use this                                                                     |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Every line where a person or company is mentioned**             | [`/v1/podcasts/mentions?entity_id=…`](/podcasts/mentions)                    |
| Episodes featuring an entity, restricted to one podcast           | [`/v1/podcasts/mentions?entity_id=…&podcast_id=…`](/podcasts/mentions)       |
| Mentions filtered by participation (host vs guest vs mention)     | [`/v1/podcasts/mentions?entity_id=…&role=guest`](/podcasts/mentions)         |
| Dialogue *about a topic* across the catalog (paraphrase tolerant) | [`/v1/podcasts/episodes/search?semantic_search=…`](/podcasts/episode-search) |
| Dialogue containing exact tokens or phrases                       | [`/v1/podcasts/episodes/search?keyword_search=…`](/podcasts/episode-search)  |

## Examples

```bash theme={"dark"}
# Every line about Sam Altman across the catalog, with 2 lines of context.
curl --get "https://api.particle.pro/v1/podcasts/mentions" \
  --data-urlencode "entity_id=sam-altman" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```bash theme={"dark"}
# Only lines where Sam Altman appears as a guest.
curl --get "https://api.particle.pro/v1/podcasts/mentions" \
  --data-urlencode "entity_id=sam-altman" \
  --data-urlencode "role=guest" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```bash theme={"dark"}
# Mentions of OpenAI inside a single podcast.
curl --get "https://api.particle.pro/v1/podcasts/mentions" \
  --data-urlencode "company_id=openai" \
  --data-urlencode "podcast_id=all-in" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

## Response

```json theme={"dark"}
{
  "entity": {"id": "…", "slug": "sam-altman", "name": "Sam Altman"},
  "data": [
    {
      "episode": {
        "id": "…",
        "title": "…",
        "published_at": "2026-04-28T10:00:00Z",
        "podcast": {"id": "…", "title": "All-In"}
      },
      "mention_count": 8,
      "mention_variants": ["Sam Altman", "Altman"],
      "windows": [
        {
          "segment": {"id": "…", "type": "INTERVIEW", "title": "…"},
          "start_seconds": 942.0,
          "end_seconds": 988.5,
          "lines": [
            {"number": 137, "speaker": "Kara Swisher",   "role": "HOST",  "start_seconds": 942.0, "end_seconds": 948.2, "text": "…"},
            {"number": 138, "speaker": "Scott Galloway", "role": "HOST",  "start_seconds": 948.5, "end_seconds": 955.1, "text": "…", "is_mention": true},
            {"number": 139, "speaker": "Kara Swisher",   "role": "HOST",  "start_seconds": 955.5, "end_seconds": 988.5, "text": "…"}
          ]
        }
      ]
    }
  ],
  "has_more": true,
  "cursor": "s.AbCd…"
}
```

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.

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

| Param             | Notes                                                         |
| ----------------- | ------------------------------------------------------------- |
| `entity_id`       | Slug or ID. Required when `company_id` is unset.              |
| `company_id`      | Slug, domain, or ID. Resolves to the company's linked entity. |
| `podcast_id`      | Restrict to mentions in one podcast.                          |
| `episode_id`      | Restrict to a single episode.                                 |
| `role`            | `guest`, `host`, `panelist`, `correspondent`, `mention`.      |
| `since` / `until` | Episode `published_at` window. ISO date.                      |
| `context_lines`   | 0–20, default 2. Lines of surrounding dialogue per 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.

## Related

* [Episode search](/podcasts/episode-search) — find dialogue by topic or phrase.
* [Transcripts → mentions in one episode](/podcasts/transcripts#transcript-mentions) — every entity mentioned in one episode (the inverse view).
* [Podcast → mentions rollup](/podcasts/overview#mentions-across-a-podcasts-episodes) — episode-level salience aggregated across one podcast.