Ad library tools

The ads in the public ad libraries of Meta, TikTok, LinkedIn and Google, by keyword, brand or advertiser. Each call costs what the data provider charges for it, usually 1 credit.

For a teardown of one competitor, use ads_get_advertiser_ads (on Google, find the advertiser with ads_search_advertisers first), then ads_get_ad for the offer and the destination.

#Search ads

ads_search_ads

Ads running on a platform's public library, by keyword or brand.

Use when: "what ads is this category running", finding the angles and offers competitors are paying for.

Not for: one advertiser's whole set, use ads_get_advertiser_ads. Google, whose library is keyed by advertiser: use ads_search_advertisers first. Organic posts, use the platform's own search tool.

Returns: List, one page per call. rows[]: platform, id, url, advertiser, advertiser_id, headline, body, format, first_shown, last_shown, active, impressions, spend, countries, placements (where it ran: facebook, instagram), cta, destination_url, media_url. Impressions and spend are the ranges the library publishes, so they are text. meta.cursor pages the next set.

Cost: 1 credit per page. Cached 24 hours.

Also takes cursor, provider, max_credits, dry_run: see common parameters.

{
  "platform": "facebook",
  "query": "creatine gummies",
  "active_only": true
}

#Find advertisers

ads_search_advertisers

The advertisers matching a brand name in Google's ad library, with their ids.

Use when: before ads_get_advertiser_ads on Google, because that library is keyed by advertiser id and one brand has one entry per region.

Not for: the ads themselves, use ads_get_advertiser_ads with the id this returns. The other libraries, which search their ads directly with ads_search_ads.

Returns: List. rows[]: platform, id, name, region, ads_estimate, website.

Cost: 1 credit. Cached 7 days.

Also takes provider, max_credits, dry_run: see common parameters.

{
  "platform": "google",
  "query": "lululemon",
  "region": "US"
}

#Get an advertiser's ads

ads_get_advertiser_ads

Every ad one advertiser is running, from a platform's public library.

Use when: a competitor teardown: what they are running, since when, and with what offer.

Not for: a keyword sweep across advertisers, use ads_search_ads. One creative in full, use ads_get_ad.

Returns: List, one page per call. rows[]: platform, id, url, advertiser, advertiser_id, headline, body, format, first_shown, last_shown, active, impressions, spend, countries, placements (where it ran: facebook, instagram), cta, destination_url, media_url. Impressions and spend are the ranges the library publishes, so they are text. meta.cursor pages the next set.

Cost: 1 credit per page, or 25 on google with details. Cached 24 hours.

Also takes cursor, provider, max_credits, dry_run: see common parameters.

{
  "platform": "google",
  "advertiser": "lululemon.com"
}

#Get an ad

ads_get_ad

One ad from a platform's public library, with its creative text and where it sends people.

Use when: reading the offer and the call to action behind an ad you found in a list.

Not for: a set of ads, use ads_search_ads or ads_get_advertiser_ads. What is said in an ad video, use the platform's transcript tool.

Returns: Record. rows[]: platform, id, url, advertiser, advertiser_id, headline, body, format, first_shown, last_shown, active, impressions, spend, countries, placements (where it ran: facebook, instagram), cta, destination_url, media_url. Impressions and spend are the ranges the library publishes, so they are text.

Cost: 1 credit. Cached 7 days.

Also takes provider, max_credits, dry_run: see common parameters.

{
  "platform": "facebook",
  "id": "1185617869915074"
}