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
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), oradvertisers, which finds advertisers by name.query: A keyword. It matches the words in an ad’s text in any order. Required unlesspageIdis set.pageId: An advertiser’s numeric Facebook page ID, such as266556540473351. It lists that advertiser’s ads, and withqueryit searches them.country: Where the ads ran, as a two-letter country code, orALLfor every country. DefaultUS.activeStatus:active(default),inactiveorall.limit: 1 to 500 ads. Default 30.cursor: ThenextCursorof an earlier response, to read the ads after it.searchType:keyword_unordered(default) orkeyword_exact_phrase.adType:all(default),political_and_issue_ads,housing_ads,employment_adsorfinancial_products_and_services_ads.mediaType:all(default),image,meme,image_and_meme,videoornone.publisherPlatforms: One or more offacebook,instagram,audience_network,messenger,whatsappandthreads, 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) ormost_recent.impressions_low_to_highneedsadTypepolitical_and_issue_ads, the only ads the library sorts that way.
400 VALIDATION_ERROR, and details names the field.
Read more ads
A response with more ads to read carriesnextCursor. 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.
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.
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,queryorpageId,activeStatusand the filters it was given. totalCountis the library’s own count of the matching ads, which the library rounds for large searches.returnedCountcounts the ads inads,hasMoreistruewhen the library has more, whichnextCursorreads, andlibraryUrlopens the same search in the Ad Library.- Each ad has
position,libraryId,libraryUrl,isActive,startDateandendDate(days in UTC),platforms,versions(how many ads use this creative and text),format(IMAGE,VIDEO,CAROUSEL,DCO,DPA,MULTI_IMAGESand others),body,title,caption,linkUrl,linkDescription,ctaText,ctaTypeandcategories(the library’s categories of the ad, such asPOLITICALorEMPLOYMENT). - The advertiser is
pageId,pageName,pageProfileUrl,pageProfilePictureUrl,pageLikeCountandpageCategories. Ads about social issues, elections or politics addbyline, who paid for the ad, anddisclaimerLabel, and a paid partnership adds the partner’s page inbrandedContent. - Media is
images(url,resizedUrl),videos(hdUrl,sdUrl,previewImageUrl) andcards, the cards of a carousel or catalog ad, each with its owntitle,body,linkUrl,caption,linkDescription,ctaText,ctaType,imageUrl,resizedImageUrlandvideo. A dynamic ad’s other texts, links, images and videos are inextraTexts,extraLinks,extraImagesandextraVideos. - 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,impressionsandreachappear 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
adsandtotalCount0.
Price
A search holds 0.5 credits for every 30 ads itslimit 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.