Track a company across podcasts

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.

curl "https://api.particle.pro/v1/companies?q=nvidia&limit=1" \
  -H "X-API-Key: $PARTICLE_API_KEY"

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();

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]

Response (truncated)

{
  "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).

curl "https://api.particle.pro/v1/podcasts/mentions?company_id=nvidia&limit=1&context_lines=1" \
  -H "X-API-Key: $PARTICLE_API_KEY"

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();

data = httpx.get(
    "https://api.particle.pro/v1/podcasts/mentions",
    params={"company_id": "nvidia", "limit": 1, "context_lines": 1},
    headers=headers,
).json()["data"]

Response (truncated)

{
  "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 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.

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"

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();

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

Response (truncated)

{
  "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:

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

Mentions for every filter on the mention endpoints
Companies for the identifier systems a company resolves from
Alerts overview for kinds, cadences, and delivery channels

Getting started

Recipes

Podcasts

Companies

Knowledge graph

Alerts

Errors

Track a company across podcasts

1. Resolve the company

2. Read every line that names it

3. Chart the volume over time

4. Hand the watching to an alert

​1. Resolve the company

​2. Read every line that names it

​3. Chart the volume over time

​4. Hand the watching to an alert

​Related

1. Resolve the company

2. Read every line that names it

3. Chart the volume over time

4. Hand the watching to an alert

Related