Skip to main content
Search the Meta Ad Library as JSON through the async task API. Send taskType ADS with platform meta_ad_library, and a keyword in query or an advertiser’s Facebook page ID in pageId. A search costs 0.5 credits for every 30 ads it returns. To find an advertiser’s page ID by name, send action advertisers.

Request

Submit the task, then poll GET /v1/async/task/{id} or receive its webhook. See Async tasks. A search of 30 ads usually completes in a few seconds, and a search of 500 ads in about a minute.

Parameters

  • action: search (default), or advertisers, which finds advertisers by name.
  • query: A keyword. It matches the words in an ad’s text in any order. Required unless pageId is set.
  • pageId: An advertiser’s numeric Facebook page ID, such as 266556540473351. It lists that advertiser’s ads, and with query it searches them.
  • country: Where the ads ran, as a two-letter country code, or ALL for every country. Default US.
  • activeStatus: active (default), inactive or all.
  • limit: 1 to 500 ads. Default 30.
  • cursor: The nextCursor of an earlier response, to read the ads after it.
  • searchType: keyword_unordered (default) or keyword_exact_phrase.
  • adType: all (default), political_and_issue_ads, housing_ads, employment_ads or financial_products_and_services_ads.
  • mediaType: all (default), image, meme, image_and_meme, video or none.
  • publisherPlatforms: One or more of facebook, instagram, audience_network, messenger, whatsapp and threads, as an array or comma-separated text.
  • contentLanguages: One or more two-letter language codes.
  • startDate, endDate: YYYY-MM-DD. Keeps the ads shown between the two days.
  • sortBy: impressions_high_to_low (default) or most_recent. impressions_low_to_high needs adType political_and_issue_ads, the only ads the library sorts that way.
A value the library cannot search is rejected with 400 VALIDATION_ERROR, and details names the field.

Read more ads

A response with more ads to read carries nextCursor. Send it as cursor with the same search to receive the next ads, again up to limit. Positions continue from the last response, and nextCursor is null once the library has no more.
A cursor works only with the search that returned it: a different query, pageId, country, activeStatus or filter is rejected with 400 VALIDATION_ERROR, while limit can change. The cursor grows with the ads read before it, to about 14 KB after 1,000 ads, so store it as text without a length limit. The library sometimes lists an ad twice, so an ad can come again in a later response; libraryId tells the repeats apart.

Find an advertiser

action advertisers returns the Facebook pages of the advertisers whose names match query, as the library’s search box suggests them. Send the pageId you pick to search that advertiser’s ads.
Each advertiser has position, pageId, name, category, likeCount, verified (Meta’s blue badge), country (the page’s country where Meta names one, such as the UK page of a global brand), pageAlias, profileUrl, pictureUrl, instagramUsername, instagramFollowerCount, instagramVerified and libraryUrl, which opens the advertiser’s ads in the Ad Library. keywords lists the searches the library suggests for the name. The library matches names as their pages spell them: Shokz finds the Shokz pages, and 샥즈 finds none. A name no page carries completes with an empty advertisers. An advertiser search takes only query and country, and costs 0.5 credits.

Response example

Result fields

  • The response echoes platform, action, country, query or pageId, activeStatus and the filters it was given.
  • totalCount is the library’s own count of the matching ads, which the library rounds for large searches. returnedCount counts the ads in ads, hasMore is true when the library has more, which nextCursor reads, and libraryUrl opens the same search in the Ad Library.
  • Each ad has position, libraryId, libraryUrl, isActive, startDate and endDate (days in UTC), platforms, versions (how many ads use this creative and text), format (IMAGE, VIDEO, CAROUSEL, DCO, DPA, MULTI_IMAGES and others), body, title, caption, linkUrl, linkDescription, ctaText, ctaType and categories (the library’s categories of the ad, such as POLITICAL or EMPLOYMENT).
  • The advertiser is pageId, pageName, pageProfileUrl, pageProfilePictureUrl, pageLikeCount and pageCategories. Ads about social issues, elections or politics add byline, who paid for the ad, and disclaimerLabel, and a paid partnership adds the partner’s page in brandedContent.
  • Media is images (url, resizedUrl), videos (hdUrl, sdUrl, previewImageUrl) and cards, the cards of a carousel or catalog ad, each with its own title, body, linkUrl, caption, linkDescription, ctaText, ctaType, imageUrl, resizedImageUrl and video. A dynamic ad’s other texts, links, images and videos are in extraTexts, extraLinks, extraImages and extraVideos.
  • Media URLs are Meta CDN links that expire after a few days. Save the files you need.
  • Catalog ads (DPA, DCO) keep the library’s placeholders, such as {{product.name}}, in their text.
  • spend, currency, impressions and reach appear only where the library discloses them: ads about social issues, elections or politics, and ads shown in the EU.
  • A search with no matching ads completes with an empty ads and totalCount 0.

Price

A search holds 0.5 credits for every 30 ads its limit asks for, and is charged 0.5 credits for every 30 ads it returns, at least 0.5 credits. The default search of 30 ads costs 0.5 credits, and a search with limit 500 holds 8.5 credits. An advertiser search costs 0.5 credits. Only completed requests are charged.