> ## 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. # Publisher advertising > Roll up ads, sponsors, and bundle-buy intelligence across every podcast a publisher owns — iHeartPodcasts, NPR, Wondery, Bloomberg, and the rest. Big podcast publishers don't sell ads one show at a time. iHeartPodcasts produces thousands of shows; a single advertiser (Public.com, Mint Mobile, Audible) commonly runs across dozens of them as a network buy. The per-podcast advertising endpoints give you one show at a time. These endpoints surface the rollup. Available to MCP agents as the `advertising` section on [`particle_podcast_get_publisher`](/mcp/tools/podcast_publishers/podcast-get-publisher) — pass `include=["advertising"]`. The sponsor→publishers flip is also exposed to agents via [`particle_company_get_podcast_ad_presence`](/mcp/tools/podcast_advertising/company-get-podcast-ad-presence) with `include=["publishers"]` (the path resolves the company ref and aggregates across all linked sponsors). The cross-publisher leaderboard remains REST-only. Use these endpoints when you want to: * See a publisher's whole ad book in one shot — total spend, unique sponsors, network buyers. * Find sponsors doing network/bundle buys across a publisher's catalog (sort by `podcast_coverage`). * Reverse the lens: given a sponsor, see every publisher whose catalog they buy into and at what coverage. * Compare publishers by monetization density (`ads_per_active_podcast`) — small sub-networks often outrank flagship catalogs. ## Publisher advertising profile The top-level rollup for a single publisher: ```bash curl theme={"dark"} curl "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/advertising" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```js JavaScript theme={"dark"} const res = await fetch( "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/advertising", { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } }, ); const profile = await res.json(); ``` ```python Python theme={"dark"} res = httpx.get( "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/advertising", headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]}, ) profile = res.json() ``` ```jsonc Response (truncated) theme={"dark"} { "publisher": { "id": "0RZ7y1ABC", "slug": "iheartpodcasts", "name": "iHeartPodcasts" }, "coverage": { "total_podcasts": 210, "active_podcasts": 150, "active_coverage": 0.714 }, "total_ads": 95605, "unique_sponsors": 1518, "episode_reach": 13914, "ads_per_active_podcast": 637.4, "read_type_breakdown": { "host_read": 51234, "pre_recorded": 44371 }, "network_buyers_count": 76, "top_sponsors": [ { "sponsor_name": "Public.com", "company_id": "public.com", "ad_count": 3852, "podcast_coverage": 93, "episode_count": 1603 }, { "sponsor_name": "Amazon", "company_id": "amazon.com", "ad_count": 1251, "podcast_coverage": 65, "episode_count": 643 }, { "sponsor_name": "Lowe's", "company_id": "lowes.com", "ad_count": 1161, "podcast_coverage": 58, "episode_count": 699 } // …up to 10 ] } ``` The `publisher` and `coverage` envelopes match the shapes used by the [publisher bias](/podcasts/publishers-bias) and [publisher suitability](/podcasts/publisher-suitability) profiles, so callers can use the same destructuring code across all three publisher-level surfaces. **`network_buyers_count`** is the bundle-buy headline: how many distinct sponsors appear on at least three of the publisher's podcasts *and* at least 25% of the catalog. A publisher with 76 network buyers is selling a lot of network inventory; a publisher with 2 is mostly selling shows individually. **`podcast_coverage`** on each top sponsor tells you how many of the publisher's podcasts that sponsor appears on. Public.com on 93 of the 210 iHeartPodcasts shows in our index is unambiguously a network buy. ## List sponsors for a publisher Drill into the full sponsor list for a publisher, sortable by ad volume or by network coverage: ```bash curl theme={"dark"} curl "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/advertising/sponsors?sort=podcast_coverage&min_podcast_coverage=20&limit=10" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```js JavaScript theme={"dark"} const res = await fetch( "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/advertising/sponsors" + "?sort=podcast_coverage&min_podcast_coverage=20&limit=10", { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } }, ); const { data, has_more, cursor } = await res.json(); ``` ```python Python theme={"dark"} res = httpx.get( "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/advertising/sponsors", params={"sort": "podcast_coverage", "min_podcast_coverage": 20, "limit": 10}, headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]}, ) body = res.json() ``` ```jsonc Response (truncated) theme={"dark"} { "data": [ { "id": "0PqRsTuV12", "name": "Public.com", "company": { "id": "public.com", "name": "Public.com" }, "ad_count": 3852, "podcast_coverage": 93, "coverage_share": 0.443, "episode_reach": 1603, "first_seen_at": "2025-02-08T16:21:43Z", "last_seen_at": "2026-05-12T11:04:55Z" }, { "name": "Amazon", "company": { "id": "amazon.com", "name": "Amazon" }, "ad_count": 1251, "podcast_coverage": 65, "coverage_share": 0.310, "episode_reach": 643 } // … ], "has_more": true, "cursor": "r.A0AAAAAo" } ``` ### Query parameters | Parameter | Default | Description | | ---------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `sort` | `ad_count` | `ad_count` ranks by total ad volume; `podcast_coverage` surfaces network buyers; `episode_reach` prioritizes episode-level breadth. | | `min_podcast_coverage` | `0` | Only return sponsors appearing on at least this many distinct publisher podcasts. Set to 10–25 to filter to obvious network buyers. | | `q` | — | Case-insensitive substring match on the sponsor name. | | `limit` | `25` | Page size, 1–100. | | `cursor` | — | Opaque cursor from the previous response's `cursor` field. | ## List publisher podcasts ranked by ad volume Ad volume diverges sharply from popularity inside a single publisher. The default catalog listing at `/v1/podcasts/publishers/{id}/podcasts` orders by popularity; this endpoint orders by total ads detected, with per-podcast monetization stats: ```bash curl theme={"dark"} curl "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/advertising/podcasts?limit=5" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```js JavaScript theme={"dark"} const res = await fetch( "https://api.particle.pro/v1/podcasts/publishers/iheartpodcasts/advertising/podcasts?limit=5", { 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/publishers/iheartpodcasts/advertising/podcasts", params={"limit": 5}, headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]}, ) body = res.json() ``` ```jsonc Response (truncated) theme={"dark"} { "data": [ { "podcast": { "id": "1c262d73...", "slug": "the-clay-travis-and-buck-sexton-show", "title": "The Clay Travis and Buck Sexton Show" }, "ad_count": 18130, "unique_sponsors": 624, "episodes_with_ads": 2563, "avg_ads_per_episode": 7.07, "read_type_breakdown": { "host_read": 12211, "pre_recorded": 5919 } }, { "podcast": { "slug": "armstrong-getty", "title": "Armstrong & Getty On Demand" }, "ad_count": 13563, "unique_sponsors": 413, "episodes_with_ads": 1494, "avg_ads_per_episode": 9.08, "read_type_breakdown": { "host_read": 7841, "pre_recorded": 5722 } } // … ] } ``` ## Sponsor to publishers (the flip) Given one sponsor — or a company, by slug or domain — list every publisher whose catalog they buy into. When the `{id}` path parameter resolves to a company (e.g. `apple.com`), the response aggregates across every deduped sponsor linked to the company; the correct view for multi-sponsor brands like Apple where the company's footprint spans several sponsor aliases. Pass a specific sponsor ID to scope to that one alias instead. ```bash curl theme={"dark"} curl "https://api.particle.pro/v1/podcasts/advertising/sponsors/public.com/publishers?limit=10" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```js JavaScript theme={"dark"} const res = await fetch( "https://api.particle.pro/v1/podcasts/advertising/sponsors/public.com/publishers?limit=10", { 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/advertising/sponsors/public.com/publishers", params={"limit": 10}, headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]}, ) body = res.json() ``` ```jsonc Response (truncated) theme={"dark"} { "data": [ { "publisher": { "id": "0RZ7y1ABC", "slug": "iheartpodcasts", "name": "iHeartPodcasts" }, "publisher_podcast_count": 210, "ad_count": 3852, "podcast_coverage": 93, "coverage_share": 0.443, "episode_reach": 1603, "first_seen_at": "2025-02-08T16:21:43Z", "last_seen_at": "2026-05-12T11:04:55Z" }, { "publisher": { "slug": "foul-territory-network", "name": "Foul Territory Network" }, "publisher_podcast_count": 23, "ad_count": 118, "podcast_coverage": 18, "coverage_share": 0.783, "episode_reach": 44 }, { "publisher": { "slug": "premiere-networks", "name": "Premiere Networks" }, "publisher_podcast_count": 4, "ad_count": 254, "podcast_coverage": 4, "coverage_share": 1.0, "episode_reach": 102 } // … ] } ``` A sponsor that hits 60–100% coverage across multiple publishers is doing network buys, not per-show buys. This is the cleanest signal we expose for that pattern. ## Cross-publisher leaderboard Rank publishers by an advertising activity metric: ```bash curl theme={"dark"} curl "https://api.particle.pro/v1/podcasts/advertising/publishers/leaderboard?metric=ads_per_active_podcast&limit=10" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` ```js JavaScript theme={"dark"} const res = await fetch( "https://api.particle.pro/v1/podcasts/advertising/publishers/leaderboard" + "?metric=ads_per_active_podcast&limit=10", { 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/advertising/publishers/leaderboard", params={"metric": "ads_per_active_podcast", "limit": 10}, headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]}, ) body = res.json() ``` ```jsonc Response (truncated) theme={"dark"} { "data": [ { "rank": 1, "publisher": { "id": "0RZ7y2DPN", "slug": "iheartpodcasts-and-dan-patrick-podcast-network", "name": "iHeartPodcasts and Dan Patrick Podcast Network" }, "coverage": { "total_podcasts": 2, "active_podcasts": 2, "active_coverage": 1.0 }, "ad_count": 17022, "unique_sponsors": 582, "episode_reach": 1693, "ads_per_active_podcast": 8511.0 }, { "rank": 2, "publisher": { "id": "0RZ7y2VOL", "slug": "iheartpodcasts-and-the-volume", "name": "iHeartPodcasts and The Volume" }, "coverage": { "total_podcasts": 15, "active_podcasts": 15, "active_coverage": 1.0 }, "ad_count": 30486, "unique_sponsors": 731, "episode_reach": 3139, "ads_per_active_podcast": 2032.4 } // … ] } ``` ### Query parameters | Parameter | Default | Description | | --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `metric` | `ad_count` | `ad_count`, `unique_sponsors`, `podcast_reach` (active podcasts), `episode_reach`, `ads_per_active_podcast`. The density metric makes small sub-networks visible. | | `min_active_podcasts` | `5` | Only rank publishers with at least this many active podcasts (catalog podcasts that have run at least one ad). Guards `ads_per_active_podcast` and the other density-style metrics against single-show publishers ranking #1 on noise. Pass `1` for no guard. | | `limit` | `25` | Page size, 1–100. | | `cursor` | — | Opaque cursor from the previous response's `cursor` field. | The publisher leaderboard reflects an all-time, MV-fresh snapshot — time-window filters are not currently exposed. Use the [sponsor leaderboard](#scoped-sponsor-leaderboard) with `publisher_id` if you need a time-windowed view scoped to one publisher. ## Scoped sponsor leaderboard The standard [sponsor leaderboard](/podcasts/advertising#sponsor-leaderboard) accepts an optional `publisher_id` query parameter — set it to scope the ranking to ads on one publisher's catalog. Like every publisher reference in the API, the parameter accepts either the publisher slug (e.g. `iheartpodcasts`) or the encoded publisher ID: ```bash theme={"dark"} curl "https://api.particle.pro/v1/podcasts/advertising/leaderboard?publisher_id=iheartpodcasts&metric=podcast_reach&limit=10" \ -H "X-API-Key: $PARTICLE_API_KEY" ``` This is the cheapest way to ask "who are the top sponsors *within* a publisher's catalog" with full Sponsor object detail (including `id` so you can pivot to other sponsor endpoints). ## Choosing the right endpoint | You want to… | Use this | | ---------------------------------------------- | ----------------------------------------------------------------------------- | | Single-number summary of a publisher's ad book | `GET /v1/podcasts/publishers/{id}/advertising` | | Find network/bundle buyers on a publisher | `GET /v1/podcasts/publishers/{id}/advertising/sponsors?sort=podcast_coverage` | | Compare a publisher's shows by monetization | `GET /v1/podcasts/publishers/{id}/advertising/podcasts` | | Map a sponsor's publisher footprint | `GET /v1/podcasts/advertising/sponsors/{id}/publishers` | | Rank all publishers by ad volume or density | `GET /v1/podcasts/advertising/publishers/leaderboard` | | Per-podcast or per-company breakdown | See [Advertising](/podcasts/advertising) | ## Related * [Advertising](/podcasts/advertising) — per-podcast, per-company, and per-episode views. * [Publishers](/podcasts/publishers) — catalog browsing endpoints for publishers themselves.