> ## 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.
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).
## Per-company advertising
The fastest way to see how a single company shows up as a sponsor:
```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()
```
```jsonc Response (truncated) theme={"dark"}
{
"company_id": "nvidia.com",
"slug": "nvidia",
"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 = ` 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", "slug": "okx", "ad_count": 7, "episode_count": 7 },
{ "sponsor_name": "Circle", "company_id": "circle.com", "slug": "circle", "ad_count": 5, "episode_count": 5 },
{ "sponsor_name": "Solana", "company_id": "solanalabs.com", "slug": "solana-labs", "ad_count": 4, "episode_count": 4 },
{ "sponsor_name": "Polymarket", "company_id": "polymarket.com", "slug": "polymarket", "ad_count": 3, "episode_count": 3 }
// …
]
}
```
A useful proxy for category fit — crypto-native sponsors dominate All-In, for example.
## Sponsors a podcast could pitch
`GET /v1/podcasts/{id}/recommendations/sponsors` flips the question for a show selling its own
inventory: which advertisers buy shows like mine, but not mine yet? It takes the show's
precomputed [related shows](/podcasts/related), collects the sponsors those shows run, and
ranks each sponsor by how related the venues are, how much it buys there, and how recently,
dropping anything already on the show's own roster. It is a prospecting list, not a
prediction: the right reading is "advertisers your peer shows carry that you do not."
The podcast detail embeds the first five with `include=recommended_sponsors` on
[`GET /v1/podcasts/{id}`](/podcasts/related#the-five-most-related-shows-inline), gated the
same way as this endpoint.
```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/all-in/recommendations/sponsors?include=via&active_since=2026-01-01&limit=3" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```json Response (truncated) theme={"dark"}
{
"data": [
{
"sponsor": { "id": "…", "name": "Polymarket", "company": { "id": "polymarket.com", "name": "Polymarket" } },
"score": 0.71,
"band": "moderate",
"shared_show_count": 4,
"total_ads": 19,
"last_ad_at": "2026-08-21T00:00:00Z",
"via": [
{ "id": "…", "title": "Invest Like the Best", "slug": "invest-like-the-best" }
]
}
],
"has_more": true,
"cursor": "r.…"
}
```
| Field | Meaning |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sponsor` | The sponsor, with its linked `company` when known. The company record is the path to outreach: [`GET /v1/companies/{id}/people`](/api-reference/companies/list-company-people) lists the people there. |
| `score`, `band` | Strength in (0,1) and its coarse class. Branch on `band`. |
| `shared_show_count`, `total_ads`, `last_ad_at` | The evidence: how many related shows run the sponsor, its ad reads across them (network promos excluded), and its most recent ad. |
| `via` | With `include=via`, the related shows that run the sponsor, strongest first (at most three) — the peer set to cite in a pitch. |
| Parameter | Meaning |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include` | `via` attaches the related shows behind each recommendation. `contacts` attaches up to three people at the sponsor's company most likely to own a sponsorship decision — marketing first, then partnerships, brand, media and advertising, communications, growth, then other executives — each with `title`, a `role` class and a `linkedin_url` when known. |
| `active_since` | Only sponsors whose most recent ad across the related shows is on or after this date — the "still buying" filter. |
| `exclude_top_advertisers` | Drop the N most active advertisers corpus-wide (by lifetime ad count). The list is strongest beyond the largest programmatic advertisers, which every list already names: 50 removes the head, 200 keeps only the long tail. |
| `min_score` | Only recommendations at or above this score. |
| `limit`, `cursor` | Standard pagination (at most 200 recommendations per show). |
A show whose related set has not been computed yet gets `200` with an empty `data` array.
Who sponsors *this* show is [`GET /v1/podcasts/{id}/advertising`](#per-podcast-advertising-summary);
a sponsor's full footprint is [`GET /v1/podcasts/advertising/sponsors/{id}/podcasts`](#sponsor-lookup).
MCP: `include: ["recommended_sponsors"]` on `particle_podcast_resolve`.
## Shows a company could advertise on next
`GET /v1/companies/{id}/podcast/recommendations` is the buy side: which shows are most like the
ones a company already advertises on, that it does not buy yet? It takes the shows the company's
sponsors run ads on, weights each by how much the company advertises there, follows each one's
precomputed [related shows](/podcasts/related), and ranks every show the company has never bought
by the compounded relatedness. In the temporal holdout it recovered the shows advertisers went on
to buy at 13× the rate of category-by-popularity and 8× the rate of "most-bought shows overall".
Premium, like the rest of the company advertising surface.
```bash theme={"dark"}
curl "https://api.particle.pro/v1/companies/betterhelp.com/podcast/recommendations?include=via&limit=3" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```json Response (truncated) theme={"dark"}
{
"data": [
{
"podcast": { "id": "…", "title": "The Mel Robbins Podcast", "slug": "the-mel-robbins-podcast" },
"score": 0.82,
"band": "strong",
"via": [
{ "id": "…", "title": "On Purpose with Jay Shetty", "slug": "on-purpose-with-jay-shetty" }
]
}
],
"has_more": true,
"cursor": "r.…"
}
```
| Field | Meaning |
| --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `podcast` | The recommended show. |
| `score`, `band` | Strength in (0,1) and its coarse class. Branch on `band`. |
| `via` | With `include=via`, the company's own shows that led here, strongest first — the venues to cite when explaining the fit. |
| Parameter | Meaning |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `include` | `via` attaches the company's own shows behind each recommendation. |
| `min_score` | Only recommendations at or above this score, applied within the list below. |
| `language` | Only shows in this language (ISO 639-1 code, e.g. `en`), applied within the list below. |
| `limit`, `cursor` | Standard pagination. The list is the 200 strongest recommendations for the company; the filters narrow that list rather than reach past it. |
A company with no podcast advertising, or whose bought shows have no computed related sets yet,
gets `200` with an empty `data` array. Where the company advertises today is
[`GET /v1/companies/{id}/podcast/advertising/podcasts`](#per-company-advertising).
MCP: `include: ["podcast_recommendations"]` on `particle_company_get`.
## 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:
```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"]
```
```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", "slug": "okx", "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", "slug": "polymarket", "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.
`company.slug` is the knowledge-graph slug and the stable key to build links from; `company.id` stays domain-preferred (`okx.com`).
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