API reference

Ads library

Written and maintained by The ProspectAPIs team

The ads library API returns whether a company is running ads now, where and since when, from four public ad libraries keyed on the company's domain: the Meta Ad Library, the Google Ads Transparency Center, the LinkedIn Ad Library and the TikTok Ad Library. Every answer carries a one-line summary, a status for each library and how the company's advertiser was found there. A field the library does not show is null, never filled in.

Launching soon: the routes below answer 503 until the ads library goes live.

GET /v1/ads

A company's live ads, newest last seen first. Pass domain (required) and, to narrow it, platform: one or more of meta, google, linkedin and tiktok, comma separated. Page with limit (1 to 100, default 25) and cursor (pass back next_cursor exactly as returned). Later pages are free and come from the same read, with no summary or library blocks. A cursor works only with the key that made the first call and expires after 6 hours; INVALID_CURSOR or STALE_CURSOR (the ads were read again since) means repeat the call without it. A later page never includes a library the first page reported unreadable. A lookup that pins an advertiser id is one page (raise limit to 100); its next_cursor is null.

curl "https://api.prospectapis.com/v1/ads?domain=acme.com&platform=meta,google" \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY"

{
  "domain": "acme.com",
  "company_id": "c3f1...",
  "summary": {
    "running_now": true, "platforms_running": 1, "ads_live_total": 12, "ads_live_is_lower_bound": false,
    "first_seen_any": "2026-08-02", "newest_creative_at": "2026-10-30",
    "sentence": "Running 12 ads on Meta, first seen 2026-08-02"
  },
  "platforms": [
    { "platform": "meta", "status": "ok", "advertiser": { "id": "100200300", "name": "Acme", "page_url": "https://www.facebook.com/acme/" },
      "resolution": { "method": "landing_domain_majority", "confidence": 0.9, "evidence": "9 of 10 ads landing on acme.com are from the page Acme" },
      "ads_live": 12, "ads_total_band": "12", "complete": true, "truncated": false, "read_at": "2026-11-01T09:30:00.000Z", "cached": false,
      "coverage": "active ads in every country; inactive ads only when they reached the EU" },
    { "platform": "google", "status": "unreadable", "reason": "rate_limited" }
  ],
  "data": [
    { "id": "meta.1234567890", "platform": "meta", "advertiser_name": "Acme", "advertiser_id": "100200300",
      "advertiser_url": "https://www.facebook.com/acme/", "creative_text": "Warehouse robots that pay for themselves in a year.",
      "media_urls": ["https://video.example.net/acme-demo.mp4"], "first_seen": "2026-10-02T07:00:00.000Z",
      "last_seen": "2026-11-01T07:00:00.000Z", "countries": null, "landing_url": "https://acme.com/demo", "status": "active",
      "format": "video", "source_url": "https://www.facebook.com/ads/library/?id=1234567890", "read_at": "2026-11-01T09:30:00.000Z" }
  ],
  "count": 1, "total": 12, "next_cursor": "eyJvIjoxLC...", "charged_usd": 0.006
}

The example shows a fictional company: Meta answered with ads and was charged; Google could not be read at that moment and was not.

A status for each library

One library that cannot be read never fails the call: you get the others with their statuses. The API answers 503 SOURCE_UNAVAILABLE only when every library you asked for is unreadable. truncated: true means the library had more ads than one read takes, so ads_live is a lower bound and ads_total_band carries the library's own count where it gives one.

How the company's advertiser is found

Each library names an advertiser, not a domain, so every answer says how the advertiser was tied to the company, strongest evidence first: caller_supplied (an id you passed), website_link (the page the company's own site links to), landing_domain_majority (the advertiser that owns most of the ads landing on the domain) and name_match (an advertiser named like the company, used last). An advertiser that only links to the domain is never taken. resolution.match says the outcome: matched, ambiguous (ads land on the domain but no one advertiser owns most of them) or no_advertiser_match. An empty list with anything but matched means no matching advertiser was found, not that the company runs no ads. When you already know the advertiser, pass it and the library is read for it directly: google_advertiser_id (AR followed by digits), meta_page_id, linkedin_company_id or tiktok_advertiser (the name as the library shows it).

GET /v1/ads/:id

One ad in full, by the id from GET /v1/ads. It adds what the library shows only on the single ad: the countries a Google ad ran in, the run dates and landing URL of a LinkedIn ad. An id we have not read answers 404, free.

curl https://api.prospectapis.com/v1/ads/meta.1234567890 \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY"

What each library covers

We read each library's public pages logged out, the way a visitor's browser does, and never with an account. A read is kept for a few hours, so calls within that window answer from it (cached: true).

Ad fields

Watch a company's ads

An ads watchlist sends a signed webhook when a company's ads change. Create it with kind: "ads" and the filters domain and, optionally, platform. By default it delivers company-level events: advertiser_started (the company starts running ads on a library), advertiser_stopped (it stops) and new_creatives (new creatives, with a count and sample ids). Set level: "ad" for every ad's own ad_started, ad_stopped and new_creative. An ad is reported stopped only after a complete read, and a read that suddenly loses most of a company's ads is checked again before anything is sent. Signing and retries follow the watchlists guide; creating is free and each delivered event costs $0.006, charged only when your webhook answers 2xx.

curl https://api.prospectapis.com/v1/watchlists \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme ads","kind":"ads","filters":{"domain":"acme.com","platform":"meta,linkedin"},"webhook_url":"https://hooks.example.com/ads"}'

Billing

A lookup costs $0.006 for each library whose status is ok, so a company running ads on two of the four is $0.012. no_ads, not_resolved, not_covered and unreadable are free, and so are later pages of the same lookup, a 404 unknown id and a 503. charged_usd in the answer says what this call cost. When you cannot pay the API answers 402 with a top_up_url.

Next steps

Create a free account to get a key; every account starts with a free $1 balance. The quickstart covers authentication and errors, company profiles and funding signals key on the same domain, and pricing lists what each call costs. Our guides to funding signals for prospecting and researching prospects with an AI agent show where a spend signal such as a company's live ads fits an account workflow.