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

# Advertising

> Sponsor analytics across the podcast catalog: leaderboards, per-company presence, and co-occurrence.

Particle API extracts every sponsor read from every transcribed episode, attributes them to a company in the [knowledge graph](/knowledge-graph/entities), and aggregates the result. You get sponsor-side analytics — who advertises where, how often, with what read style — without scraping audio yourself.

<Note>Available to MCP agents in the opt-in `podcast_advertising` category as [`particle_company_get_podcast_ad_presence`](/mcp/tools/podcast_advertising/company-get-podcast-ad-presence), [`particle_podcast_get_sponsors`](/mcp/tools/podcast_advertising/podcast-get-sponsors), and [`particle_podcast_get_sponsor_leaderboard`](/mcp/tools/podcast_advertising/podcast-get-sponsor-leaderboard).</Note>

## Per-company advertising

The fastest way to see how a single company shows up as a sponsor:

<CodeGroup>
  ```bash curl theme={"dark"}
  curl "https://api.particle.pro/v1/companies/nvidia/podcast/advertising" \
    -H "X-API-Key: $PARTICLE_API_KEY"
  ```

  ```js JavaScript theme={"dark"}
  const res = await fetch(
    "https://api.particle.pro/v1/companies/nvidia/podcast/advertising",
    { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
  );
  const summary = await res.json();
  ```

  ```python Python theme={"dark"}
  res = httpx.get(
      "https://api.particle.pro/v1/companies/nvidia/podcast/advertising",
      headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
  )
  summary = res.json()
  ```
</CodeGroup>

```jsonc Response (truncated) theme={"dark"}
{
  "company_id": "nvidia.com",
  "total_ads": 13,
  "podcast_reach": 3,
  "episode_reach": 10,
  "read_type_breakdown": { "host_read": 12, "pre_recorded": 1 },
  "recent_ads": [
    {
      "sponsor_name": "NVIDIA Studio",
      "read_type": "HOST_READ",
      "placement_type": "PRE_ROLL",
      "start_seconds": 14.2,
      "end_seconds": 78.6,
      "duration_seconds": 64.4,
      "podcast": { "title": "Giant Bombcast", "slug": "giant-bombcast" },
      "created_at": "2026-03-26T02:22:26Z"
    },
    {
      "sponsor_name": "NVIDIA",
      "product": "Arc Raiders",
      "read_type": "HOST_READ",
      "placement_type": "PRE_ROLL",
      "podcast": { "title": "Kinda Funny Gamescast", "slug": "kinda-funny-gamescast" }
    }
    // …
  ]
}
```

`read_type_breakdown` distinguishes host-reads from pre-recorded spots. `placement_type` distinguishes `PRE_ROLL` / `MID_ROLL` / `POST_ROLL`. `recent_ads` includes per-product attribution where the read called out a specific product line, plus segment timing within the episode — see [Per-episode ads](#per-episode-ads) below for details.

To see *which podcast publishers* a company advertises across — and how much of each publisher's catalog it covers — use the [sponsor→publishers flip](/podcasts/publishers-advertising#sponsor-to-publishers-the-flip) and pass the company's slug or domain as the `{id}` path parameter. When the value resolves to a company (not a specific sponsor), the response aggregates every ad with `sponsor_company_id = <company>` across all the company's deduped sponsors. Pass a specific sponsor ID to scope to that single alias instead.

## Per-podcast advertising summary

Same idea, inverted — for a single podcast, who's sponsoring it?

```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/all-in/advertising" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```jsonc Response (truncated) theme={"dark"}
{
  "total_ads": 47,
  "top_sponsors": [
    { "sponsor_name": "OKX",        "company_id": "okx.com",        "ad_count": 7, "episode_count": 7 },
    { "sponsor_name": "Circle",     "company_id": "circle.com",     "ad_count": 5, "episode_count": 5 },
    { "sponsor_name": "Solana",     "company_id": "solanalabs.com", "ad_count": 4, "episode_count": 4 },
    { "sponsor_name": "Polymarket", "company_id": "polymarket.com", "ad_count": 3, "episode_count": 3 }
    // …
  ]
}
```

A useful proxy for category fit — crypto-native sponsors dominate All-In, for example.

## Per-episode ads

When you already have an episode in hand — for example, drilling in after `list-episodes` or after a transcript-based search — fetch the individual ad reads detected in that episode:

<CodeGroup>
  ```bash curl theme={"dark"}
  curl "https://api.particle.pro/v1/podcasts/episodes/78cgekLUjCJBUZbj3s5K8Y/ads" \
    -H "X-API-Key: $PARTICLE_API_KEY"
  ```

  ```js JavaScript theme={"dark"}
  const res = await fetch(
    "https://api.particle.pro/v1/podcasts/episodes/78cgekLUjCJBUZbj3s5K8Y/ads",
    { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
  );
  const { data } = await res.json();
  ```

  ```python Python theme={"dark"}
  res = httpx.get(
      "https://api.particle.pro/v1/podcasts/episodes/78cgekLUjCJBUZbj3s5K8Y/ads",
      headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    {
      "id": "5n8KqRrPmTyVxWzAbCdEf2",
      "sponsor_name": "OKX",
      "product": "OKX Wallet",
      "offer_description": "Sign up at okx.com/allin",
      "sponsor_url": "https://www.okx.com/allin",
      "read_type": "HOST_READ",
      "placement_type": "MID_ROLL",
      "start_seconds": 2110.3,
      "end_seconds": 2246.5,
      "duration_seconds": 136.2,
      "company": { "id": "okx.com", "name": "OKX" },
      "podcast": { "title": "All-In with Chamath, Jason, Sacks & Friedberg", "slug": "all-in" },
      "created_at": "2026-04-12T14:08:31Z"
    },
    {
      "sponsor_name": "Polymarket",
      "read_type": "HOST_READ",
      "placement_type": "PRE_ROLL",
      "start_seconds": 12.0,
      "end_seconds": 47.8,
      "duration_seconds": 35.8,
      "company": { "id": "polymarket.com", "name": "Polymarket" },
      "podcast": { "title": "All-In with Chamath, Jason, Sacks & Friedberg", "slug": "all-in" }
    }
    // …
  ],
  "has_more": false
}
```

`company` resolves the sponsor read to a knowledge-graph company so you can join against [company endpoints](/companies/overview). Network promos (cross-promotion of other shows in the same network) are filtered out. For rolled-up views across episodes, see [Per-podcast advertising summary](#per-podcast-advertising-summary) and the [Sponsor leaderboard](#sponsor-leaderboard) below.

Each ad carries the segment timing — `start_seconds`, `end_seconds`, `duration_seconds` — measured against the episode timeline. That's enough to align ads with the transcript, measure read length, or join with the raw audio offset for downstream analysis.

## Sponsor leaderboard

The most-active sponsors across the catalog:

```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/advertising/leaderboard?limit=5" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    { "rank": 1, "sponsor": { "name": "Grainger",    "company": { "id": "grainger.com",    "name": "W. W. Grainger" } },        "ad_count": 14055, "podcast_reach": 538, "episode_reach": 9621 },
    { "rank": 2, "sponsor": { "name": "Mint Mobile", "company": { "id": "mintmobile.com",  "name": "Mint Mobile" } },           "ad_count": 9935,  "podcast_reach": 610, "episode_reach": 8809 },
    { "rank": 3, "sponsor": { "name": "Shopify",     "company": { "id": "shopify.com",     "name": "Shopify" } },               "ad_count": 9288,  "podcast_reach": 576, "episode_reach": 8237 },
    { "rank": 4, "sponsor": { "name": "Progressive", "company": { "id": "progressive.com", "name": "Progressive Corporation" } }, "ad_count": 8216, "podcast_reach": 607, "episode_reach": 5604 },
    { "rank": 5, "sponsor": { "name": "FanDuel",     "company": { "id": "fanduel.com",     "name": "FanDuel" } },               "ad_count": 7298,  "podcast_reach": 279, "episode_reach": 5394 }
    // …
  ]
}
```

Filter by `metric` (`ad_count`, `podcast_reach`, or `episode_reach`) to change the ranking dimension; by `since` / `until` to scope to a time window; by `company_id` to constrain results to one sponsor's brand family; or by `publisher_id` (slug or ID) to restrict the leaderboard to ads on one publisher's catalog — useful for asking "who are the top sponsors *within* iHeartPodcasts."

## Sponsor co-occurrence

Which sponsors run alongside each other on the same episodes — a useful signal for media-buying overlap, attribution analysis, or competitive positioning:

```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/advertising/co-occurrence?limit=5" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    {
      "sponsor_a": { "name": "Indeed",   "company": { "id": "indeed.com",   "name": "Indeed" } },
      "sponsor_b": { "name": "FanDuel",  "company": { "id": "fanduel.com",  "name": "FanDuel" } },
      "shared_episodes": 1172
    },
    {
      "sponsor_a": { "name": "Shopify",     "company": { "id": "shopify.com",    "name": "Shopify" } },
      "sponsor_b": { "name": "Mint Mobile", "company": { "id": "mintmobile.com", "name": "Mint Mobile" } },
      "shared_episodes": 1072
    }
    // …
  ]
}
```

## Sponsor lookup

Resolve a sponsor by domain, slug, or canonical ID, then list the podcasts they sponsor:

```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/advertising/sponsors/grainger.com" \
  -H "X-API-Key: $PARTICLE_API_KEY"

curl "https://api.particle.pro/v1/podcasts/advertising/sponsors/grainger.com/podcasts?limit=10" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

## Sponsor ad segments

List the individual ad segments attributed to a sponsor — newest episodes first — optionally scoped to a single podcast. Results agree with the `ad_count` values from the sponsor podcasts endpoint, so a podcast reporting 30 ads yields exactly 30 segments here. Network promos are excluded.

```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/advertising/sponsors/grainger.com/segments?podcast_id=all-in&limit=25" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

Each row is a standard [segment](/podcasts/segments-and-clips) with `read_type`, timecodes, `audio_url`, and the parent episode. Use `since`/`until` to window by episode publication date.

## Publisher-level rollups

To roll up ads across every podcast a publisher owns — total ads, network buyers, top sponsors with podcast coverage — see [Publisher advertising](/podcasts/publishers-advertising). That page covers the publisher profile, the publisher sponsors list (the bundle-buy signal), the sponsor→publishers flip, and the cross-publisher leaderboard.

## Related

* [Publisher advertising](/podcasts/publishers-advertising) — bundle-buy intelligence rolled up across a publisher's catalog
* [Companies → Overview](/companies/overview) — resolve any company by ticker, domain, or CIK before pulling its ad presence
* [Concepts → Pricing weight](/concepts#pricing-weight) — advertising endpoints are priced higher per call
* [Knowledge graph → Entities](/knowledge-graph/entities) — sponsors map to entities for cross-content tracking