# Ads across platforms: `ads/all`

One call returns a brand's ads from up to 11 ad libraries in one shape:
- Meta
- Google Search/Display, YouTube, Google Shopping
- LinkedIn
- Microsoft/Bing
- TikTok, plus TikTok top ads
- Snapchat
- Pinterest
- Apple Search Ads

It also returns a free count of the brand's Google ads. All the data is bought from providers (Apify actors and Google's
own Ads Transparency Center), not derived by us. The raw provider record is kept on every ad.

```
GET https://fetchapi.co/api/v1/ads/all?brand=Nike&domain=nike.com
header: x-api-key: gw_...
```

A default run (9 platforms, 10 ads each) for Nike took 34 s and cost $0.055. Set `per_platform` to what you will read:
cost scales with ads returned.

## Parameters

| Param | Default | Meaning |
|---|---|---|
| `brand` | required | Advertiser / brand name (`Nike`, `Notion`, `Temu`) |
| `domain` | none | The brand's site (`nike.com`). Strongly recommended: Google, YouTube and Shopping search by it, Microsoft falls back to ads landing on it, and every ad gets `lands_on_domain` |
| `platforms` | `meta,google,linkedin,microsoft,tiktok,snapchat,pinterest,apple,youtube` | Comma-separated subset. `shopping` and `tiktok_top` run only when named |
| `per_platform` | 50 | Ads per platform, 1-500 |
| `details` | off | `1` = LinkedIn ad details (paid_by, impressions, targeting): slower |
| `only_brand` | off | `1` = return only ads whose advertiser matches the brand |
| `app` | none | Apple: app name(s) or App Store id(s), comma-separated (`Royal Match`) |
| `country` | all | Meta country filter; TikTok top-ads market (default US) |
| `facebook_page_id` | looked up | The brand's Facebook page id (skips the lookup) |

## Platforms: where the data comes from, coverage, price

| Platform | Source | Coverage | Price (measured 2026-11-13) | Notes |
|---|---|---|---|---|
| `meta` | Meta Ad Library via Apify (getanyapi, blackfalcondata) | global | ~$0.00065 an ad | the brand's own page is found first (`page_found_by`) |
| `google` | Google Ads Transparency via Apify (automation-lab) | global, US region | $0.00008 an ad + $0.005 a run | first/last seen, minimum impressions; no ad text |
| `youtube` | Google Ads Transparency, YouTube filter (jaybird) | global | $0.00038 an ad | the brand's own Google advertiser ids are resolved first, so resellers (nike.com.br) are not fetched or billed |
| `shopping` | Google Ads Transparency, Shopping filter (jaybird) | global | $0.00038 an ad | opt-in; same advertiser-id resolution |
| `linkedin` | LinkedIn Ad Library (jmlp) | global | ~$0.002 a brand (billed by run time, 15-45 s) | only company advertisers whose name starts with the brand (people like "Nike Boor" are dropped); `details=1` adds paid_by, impressions, targeting |
| `microsoft` | Microsoft Ads Library (monkey.d.scraping) | **EU ads only** | $0.00045 an ad | falls back to ads landing on `domain` |
| `tiktok` | TikTok Commercial Content Library (rastriq) | **EU ads only** | $0.0009 an ad + $0.0005 a run | finds the brand's EU legal entities ("NIKE Retail B.V.", "Nike, Inc."); when the EU library has none, adds Creative Center top ads whose brand name matches |
| `tiktok_top` | TikTok Creative Center top ads (azzouzana) | global incl. US | $0.001 an ad + $0.005 a run | **top ads whose title matches the keyword, not the brand's ads**; CTR, likes, budget level |
| `snapchat` | Snap Ads Library (alexmorain) | **EU ads only** | $0.0008 an ad + $0.002 a run | |
| `pinterest` | Pinterest Ads Repository (maximedupre) | **EU ads only** (DE, FR, IT, ES, NL) | $0.00015 an ad | |
| `apple` | Apple Ad Repository (rastriq) | **EU ads only** | $0.00035 an ad + $0.002 a run | by developer name, plus `app=` |
| Google count | Google Ads Transparency Center (free RPC) | global | free | `google.runs_ads`, `google.creative_count` (+ `creative_count_upper` for big advertisers), advertiser names |

EU-only means the platform publishes an ad library only for the EU (Digital Services Act). Those platforms have no
public source for US ads. For TikTok in the US, `tiktok_top` is the only public view.

## Response

```json
{
  "brand": "Nike", "domain": "nike.com",
  "google": { "runs_ads": true, "creative_count": 50000, "creative_count_upper": 60000, "advertisers": ["Nike, Inc."] },
  "summary": {
    "meta":   { "status": "ok", "ads": 10, "brand_ads": 10, "page_id": "15087023444", "page_found_by": "...", "seconds": 12, "cost_usd": 0.0065 },
    "tiktok": { "status": "ok", "ads": 10, "brand_ads": 2, "eu_only": true, "seconds": 37, "cost_usd": 0.01 }
  },
  "total": 90, "brand_ads": 70,
  "ads": [
    { "platform": "meta", "ad_id": "...", "advertiser": "Nike", "format": "video", "text": "...", "media": "https://...",
      "landing": "https://www.nike.com/...", "first_seen": "2026-10-01", "last_seen": "2026-11-12", "days_running": 42,
      "impressions": "100K-200K", "url": "https://www.facebook.com/ads/library/?id=...",
      "matches_brand": true, "lands_on_domain": true, "raw": { } }
  ]
}
```

- **`summary` per platform:**
  - `status` (`ok`, `error_<code>`, `unsupported`);
  - `ads` returned, and `brand_ads` among them;
  - `eu_only`, `seconds`, and the platform's own `cost_usd`.
- **`matches_brand`:** the advertiser's name starts with the brand's words.
- **`lands_on_domain`:** the ad's landing page is on `domain`. This is the stronger signal; it is null without `domain`,
  or when the platform hides the landing page.
- **Keyword searches also return other advertisers** (resellers, look-alikes). Filter on `lands_on_domain`, or pass
  `only_brand=1`.
- **Fields a platform does not publish are null.** Google has no ad text; EU libraries give reach ranges instead of
  impressions.

## Recipes

**Every ad a competitor runs, cheaply**
```
/api/v1/ads/all?brand=Notion&domain=notion.com&per_platform=20&only_brand=1
```

**Does a brand advertise on Google at all, for free**
```
/api/v1/ads/all?brand=Linear&domain=linear.app&platforms=google&per_platform=1
```
Read `google.runs_ads` and `google.creative_count`.

**Mobile app ads**
```
/api/v1/ads/all?brand=Dream Games&app=Royal Match&platforms=apple,meta,tiktok,tiktok_top
```
- Meta's Audience Network placement covers in-app ads on Meta.
- Apple shows App Store search ads.

**One platform in depth**
- `/api/v1/facebook/ads?page_id=<id>&country=US` for every ad of one Facebook page.
- `/api/v1/x/ads` for X.

## Google Ads spend and history: `spyfu/domain`

```
GET https://fetchapi.co/api/v1/spyfu/domain?domain=notion.com            (or domains=a.com,b.com, up to 50)
```

SpyFu's data for a domain (owner keys; Apify clearpath/spyfu-scraper; $0.005 a run + $0.007 a domain; ~6 s):

| Section | What it holds (notion.com, Oct 2026) |
|---|---|
| `overview` | Google Ads budget estimate $127,300/mo, 54,630 paid clicks, 9,372 paid keywords, avg ad position 2.4, 329,600 organic clicks, organic value $1.37M/mo, first seen 2007-12 |
| `history` | the same numbers every month (`months=24` default, `months=all` = since 2007) |
| `ads` | ad copies it ran: title, body, landing page, avg position, share of ads served |
| `ads_by_keyword` | per keyword, the ads shown on it by date |
| `paid_keywords`, `organic_keywords` | top keywords with volume, CPC, clicks, rank, URL |
| `competitors` | `organic`, `paid`, `both` with shared keyword counts |
| `keyword_changes` | just fell off, newly ranked, gained / lost ranks, page one, ... (totals + top 5 each) |
| `ranking_trend`, `backlinks`, `countries` | monthly organic trend, sample backlinks, countries SpyFu covers for the domain |

`sections=overview,ads` returns only those parts. SpyFu's numbers are model estimates: compare domains with each other,
not with a site's own analytics.

## Not covered

- **In-app ad networks** (AdMob, AppLovin, Unity, Mintegral, Pangle, ironSource), **spend estimates across platforms**,
  and **creative history of ads that have stopped running**. No public library or Apify actor provides these.
  Commercial providers with an API:
  - Foreplay: Meta, TikTok, YouTube, LinkedIn; $59/mo for 10k ads.
  - GameAnalytics MarketIQ: 100+ mobile networks, spend; $499/mo + $0.20 a call.
  - AppGrowing: mobile ads; MCP only, price by quote.
  - Sensor Tower Pathmatics: modelled spend; quote.

  Research: `staging/ad-intel-sources.yml`.
- **Google Ads spend and ad copy history:** use `GET /api/v1/spyfu/domain?domain=notion.com` (below).
- **Reddit** has no brand ad library.
- **X:** use `/api/v1/x/ads` with the handle.

Benchmark behind the provider choices (61 live runs on Nike, Notion, Temu and Royal Match): `.context/ads-bench/`;
providers found: `staging/ads-sources.yml`.