Search a company's ads

Written and maintained by The ProspectAPIs team

GET/v1/ads

GET /v1/ads is the ProspectAPIs operation searchAds, in the Ads group of the REST API. Whether a company runs ads now on the public Meta, Google, LinkedIn and TikTok ad libraries, by domain: a summary, a status per library (ok, no_ads, not_resolved, not_covered, unreadable) with the advertiser and how it was resolved, and the live ads, newest last seen first. Each library is read logged out and cached for a few hours. Costs $0.006 per library whose status is ok, on the first page; everything else is free. One unreadable library never fails the call; 503 SOURCE_UNAVAILABLE only when every library asked for is unreadable. Coverage: Meta worldwide (active ads; inactive ones only when they reached the EU); Google worldwide (the last 30 days); LinkedIn ads run since 2023-06-01, with run dates and reach only for ads shown in the EU; TikTok only ads shown in the EEA, Switzerland and the UK. Cost: Launching soon. Send your API key as a Bearer token in the Authorization header.

How this fits with the rest of the ads API, with worked examples, is in the ads library guide.

Parameters

Parameters of GET /v1/ads
Name	In	Type	Description
domain required	query	string	The company's bare domain.
platform	query	string	One or more of meta, google, linkedin, tiktok, comma separated. Omit for all four.
google_advertiser_id	query	string	Pin the Google advertiser (AR followed by digits).
meta_page_id	query	string	Pin the Facebook page by its numeric id.
linkedin_company_id	query	string	Pin the LinkedIn company by its numeric id.
tiktok_advertiser	query	string	Pin the TikTok advertiser by its name as the library shows it.
limit	query	integer	Ads per page, 1 to 100 (default 25).
cursor	query	string	next_cursor from the previous page. Later pages are free and come from the same read, never from a library the first page reported unreadable; a cursor works only with the key that made the first call and expires after 6 hours, and INVALID_CURSOR or STALE_CURSOR means repeat the call without it. A lookup that pins an advertiser id is one page (next_cursor null).

An unknown query parameter is refused with a 400 rather than ignored, so a typo never widens a search you pay for.

Responses

Response codes of GET /v1/ads
Status	Meaning
200	Each library's status and the live ads (possibly none).
400	The request was invalid (e.g. a bad filter or input); nothing was charged.
401	The API key is missing or invalid.
402	Out of credits. The body carries top_up_url; nothing was charged.
429	Too many requests; retry after the window.
503	Every library asked for is unreadable right now. No list is returned and nothing is charged. Retry after Retry-After seconds.

Every error answers with the same JSON body, an error string and sometimes a code; the errors page lists each status and when it happens. A per-key 429 carries Retry-After; see rate limits.

200 response fields

Each library's status and the live ads (possibly none). The body is a AdsList.

Fields of the 200 response
Field	Type	Description
domain required	string
company_id	string (uuid) or null	The company record's id, when we hold one for the domain.
summary required	AdsSummary
summary.running_now	boolean
summary.platforms_running	integer
summary.ads_live_total	integer
summary.ads_live_is_lower_bound	boolean
summary.first_seen_any	string (date) or null
summary.newest_creative_at	string (date) or null
summary.sentence	string
platforms required	array of AdsPlatformRead	One library's answer. status ok, no_ads, not_resolved, not_covered or unreadable; only no_ads is an authoritative empty, and only ok is charged.
platforms[].platform required	string: meta, google, linkedin, tiktok
platforms[].status required	string: ok, no_ads, not_resolved, not_covered, unreadable
platforms[].reason	string	unreadable only: rate_limited, blocked, timeout, parse, platform_off, no_egress, reader_unavailable.
platforms[].advertiser	object or null
platforms[].resolution	object or null	How the advertiser was tied to the company.
platforms[].ads_live	integer
platforms[].ads_total_band	string or null	The library's own count or band, where it gives one.
platforms[].complete	boolean
platforms[].truncated	boolean	More ads than one read takes: ads_live is a lower bound.
platforms[].read_at	string (date-time)
platforms[].cached	boolean
platforms[].held	boolean	A read that disagreed sharply with the last one is held until a second read agrees; the last applied read is shown.
platforms[].coverage	string or null
data required	array of Ad	One ad as its library shows it. A field the library does not show is null, never filled in.
data[].id required	string	Our id: the platform, a dot, and the library's own id.
data[].platform required	string: meta, google, linkedin, tiktok
data[].advertiser_name required	string or null
data[].advertiser_id required	string or null	The library's id for the advertiser (a page id, an advertiser id, a company id). TikTok shows none.
data[].advertiser_url required	string (uri) or null
data[].creative_text required	string or null	The ad's text. Google and TikTok list views show none.
data[].media_urls required	array of string (uri)	Image and video URLs as the library serves them; some expire.
data[].first_seen required	string (date-time) or null	When the library says the ad started.
data[].last_seen required	string (date-time) or null	When the library says the ad was last shown.
data[].countries required	array of string or null	ISO 3166-1 alpha-2 codes, where the library names them (often only on GET /v1/ads/{id}).
data[].landing_url required	string (uri) or null
data[].status required	string or null: active, inactive,	Meta states it; for Google it is active when last shown within 2 days of the read; LinkedIn and TikTok state none.
data[].format required	string or null
data[].source_url required	string (uri)	The ad on its public library page.
data[].read_at required	string (date-time) or null	When we read it from the library.
count required	integer
total required	integer
next_cursor required	string or null
charged_usd required	number	What this call cost.

Response headers
Header	Meaning
X-Credits-Remaining	USD credits left after this call settles.
RateLimit-Limit	Requests this API key may make per minute.
RateLimit-Remaining	Requests left in the current one-minute window.
RateLimit-Reset	Seconds until the current window resets.

Code samples

Each sample sends the same request. Set PROSPECTAPIS_KEY in your environment first. Values come from the spec's examples; replace them with your own.

curl

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

JavaScript (fetch)

const params = new URLSearchParams({ domain: "acme.com", platform: "meta,google" });
const res = await fetch(`https://api.prospectapis.com/v1/ads?${params}`, {
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

Python (requests)

import os, requests

res = requests.get(
    "https://api.prospectapis.com/v1/ads",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    params={"domain": "acme.com", "platform": "meta,google"},
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)

Billing

Billing reserves before it serves: the call holds what it may cost, serves at most what that hold covers, and refunds the rest when the response closes. Any non-2xx answer refunds the whole hold, so a failed call costs nothing. The response reports your balance in X-Credits-Remaining.

The ads library guide covers this area end to end. Previous operation: Get one launch event. Next operation: Get one ad. Every operation, grouped by area, is on the API reference index.

Create a free account to get a key, then run the samples above with your own values.

Was this page helpful?