> ## 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.
# Track a company across podcasts
> Resolve a company once, read every line that names it, chart how often it comes up week by week, then hand the watching to an alert with a webhook.
Four calls take you from a company name to a standing watch: resolve the name to a slug, read the dialogue that names it, measure how the volume moves over time, and create an alert so new mentions come to you. Every example below was run against `https://api.particle.pro`.
## 1. Resolve the company
Search by name, ticker, domain, CIK, or Wikidata QID. The record carries every identifier, and the nested `entity.slug` is the handle the podcast endpoints take.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/companies?q=nvidia&limit=1" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const res = await fetch("https://api.particle.pro/v1/companies?q=nvidia&limit=1", {
headers: { "X-API-Key": process.env.PARTICLE_API_KEY },
});
const { data: [company] } = await res.json();
```
```python Python theme={"dark"}
import os, httpx
headers = {"X-API-Key": os.environ["PARTICLE_API_KEY"]}
company = httpx.get(
"https://api.particle.pro/v1/companies",
params={"q": "nvidia", "limit": 1},
headers=headers,
).json()["data"][0]
```
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{
"id": "3CensCwu5G2oKCFgPrNf89",
"name": "Nvidia",
"identifiers": {
"ticker": "NVDA",
"domain": "nvidia.com",
"cik": "0001045810",
"entity": { "slug": "nvidia" }
}
}
],
"has_more": true
}
```
Already holding a ticker? `GET /v1/companies?ticker=NVDA` skips the name match. The rest of this recipe uses the slug `nvidia`, which every `company_id` parameter accepts alongside the domain and the canonical id.
## 2. Read every line that names it
`GET /v1/podcasts/mentions` returns dialogue grouped by episode, newest first, with the lines around each mention and the matched line flagged. `context_lines` sets how many surrounding lines you get (default 2, up to 20).
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/mentions?company_id=nvidia&limit=1&context_lines=1" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const url = new URL("https://api.particle.pro/v1/podcasts/mentions");
url.searchParams.set("company_id", "nvidia");
url.searchParams.set("limit", "1");
url.searchParams.set("context_lines", "1");
const res = await fetch(url, { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } });
const { data } = await res.json();
```
```python Python theme={"dark"}
data = httpx.get(
"https://api.particle.pro/v1/podcasts/mentions",
params={"company_id": "nvidia", "limit": 1, "context_lines": 1},
headers=headers,
).json()["data"]
```
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{
"episode": {
"id": "1afKNpnDRxqGljnpfvJppU",
"title": "Diffraction Limit, Microscopy, and Cell Biology | Eric Betzig on Super-Resolution Microscopy",
"published_at": "2026-09-08T15:00:00Z",
"podcast": { "title": "632nm", "slug": "632nm" }
},
"mention_count": 1,
"mention_variants": ["Nvidia"],
"windows": [
{
"segment": { "type": "INTERVIEW", "title": "Diffraction Limits and Living Cells" },
"start_seconds": 435.36,
"end_seconds": 446.679,
"lines": [
{ "speaker": "Mikhail Shalaginov", "role": "HOST", "text": "Mm" },
{ "speaker": "Eric Betzig", "role": "GUEST", "text": "... then go into the ASML machines, that then go into making Nvidia chips, and so forth.", "is_mention": true },
{ "speaker": "Eric Betzig", "role": "GUEST", "text": "And, um, that is the closest I've ever seen to alien technology in my life." }
]
}
]
}
],
"has_more": true,
"cursor": "s.…",
"company": { "slug": "nvidia", "name": "Nvidia" }
}
```
An episode's whole mention set always arrives in one page, so `mention_count` and `windows` are complete for each episode you see. Narrow the walk with `podcast_id`, `publisher_id`, `role` (`guest`, `host`, and so on), `language`, `since`, and `until`; ad reads are excluded unless you pass `include_ads=true`. Page with the [loop](/recipes/pagination) when you want everything.
## 3. Chart the volume over time
For "how often, and is it rising", call the timeseries instead of paging mentions once per week. `interval` is `day`, `week`, or `month`; `published_after` and `published_before` bound the window.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/mentions/timeseries?company_id=nvidia&interval=week&published_after=2026-08-01" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const url = new URL("https://api.particle.pro/v1/podcasts/mentions/timeseries");
url.searchParams.set("company_id", "nvidia");
url.searchParams.set("interval", "week");
url.searchParams.set("published_after", "2026-08-01");
const series = await (await fetch(url, { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } })).json();
```
```python Python theme={"dark"}
series = httpx.get(
"https://api.particle.pro/v1/podcasts/mentions/timeseries",
params={"company_id": "nvidia", "interval": "week", "published_after": "2026-08-01"},
headers=headers,
).json()
```
```jsonc Response (truncated) theme={"dark"}
{
"interval": "week",
"start": "2026-07-27",
"end": "2026-09-08",
"total_mentions": 23744,
"total_episodes": 8368,
"distinct_podcasts": 3059,
"buckets": [
{ "start": "2026-07-27", "episode_count": 178, "mention_count": 430 },
{ "start": "2026-08-03", "episode_count": 1365, "mention_count": 3044 },
{ "start": "2026-08-10", "episode_count": 1457, "mention_count": 3789 },
{ "start": "2026-08-17", "episode_count": 1373, "mention_count": 3385 }
// …
]
}
```
Every bucket in the window comes back in one response, up to 1,000 buckets, so a daily series should cover at most about three years and anything longer should use weeks or months. The first bucket is the partial week the window opened in, so compare full weeks to each other.
## 4. Hand the watching to an alert
An alert watches one entity and delivers every new match by email, Slack, or a signed webhook. Create one for the company with `REALTIME` cadence and a webhook connection you created on [Deliver alerts to a webhook](/alerts/webhooks):
```bash theme={"dark"}
curl -X POST "https://api.particle.pro/v1/projects/$PARTICLE_PROJECT_ID/alerts" \
-H "X-API-Key: $PARTICLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Nvidia mentions on podcasts",
"kind": "ENTITY_MENTION",
"delivery_cadence": "REALTIME",
"entities": [
{ "entity_type": "COMPANY", "entity_id": "3CensCwu5G2oKCFgPrNf89" }
],
"notifications": [
{ "type": "WEBHOOK", "webhook_connection_id": "Wd9k2Lp7Qm3xZ" }
]
}'
```
Alerts take the company's canonical id (`3CensCwu5G2oKCFgPrNf89` from step 1). From then on each match arrives as an `alert.match.created` POST. Its `match.windows[].lines` carry the same line shape as step 2 (`speaker`, `role`, `start_seconds`, `end_seconds`, `text`, `is_mention`), so the line-level code you wrote for mentions applies; the episode block is flattened (`episode.podcast_title`, `episode.podcast_slug`, no `segment` per window) and each window adds a `clip_url`, so map that part separately. The exact payload is on [Deliver alerts to a webhook](/alerts/webhooks#the-payload). Alerts are included with the Team, Business, and Enterprise plans; preview how often one would fire before creating it with `POST /v1/projects/{projectId}/alerts/preview`. The full lifecycle is on [Create and manage alerts](/alerts/create).
## Related
* [Mentions](/podcasts/mentions) for every filter on the mention endpoints
* [Companies](/companies/overview) for the identifier systems a company resolves from
* [Alerts overview](/alerts/overview) for kinds, cadences, and delivery channels