Search ads by keyword
Search the Facebook Ad Library for public Facebook and Instagram ads matching a keyword or phrase. Filter by country, active status, media type, publisher platform, ad language and impression date, and page through the results with a cursor.
/search-ads Ads https://api.fetchlayer.dev/facebook-ad-library/search-ads Headers
Authorization string required Bearer token — your FetchLayer API key.
Parameters
query string required Keyword or phrase to search the Ad Library for.
searchType string optional keyword_unordered or keyword_exact_phrase. (default: keyword_unordered)
pageIds string[] optional Restrict the keyword search to these advertiser page ids (max 50).
country string optional Two-letter country code, or ALL. (default: ALL)
countries string[] optional Several countries at once (max 20). Overrides country.
activeStatus string optional active, inactive, or all. (default: active)
adType string optional ALL or POLITICAL_AND_ISSUE_ADS. (default: ALL)
mediaType string optional all, image, meme, image_and_meme, video, or none.
publisherPlatforms string[] optional FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, WHATSAPP, THREADS, OCULUS, UNKNOWN.
contentLanguages string[] optional Two-letter ad language codes, for example en or es.
bylines string[] optional Political-ad disclaimers ("paid for by").
startDateFrom string optional Only ads whose impressions start on or after this YYYY-MM-DD date.
startDateTo string optional Only ads whose impressions start on or before this YYYY-MM-DD date.
isTargetedCountry boolean optional Restrict to ads targeting the country rather than merely reaching it.
limit number optional Maximum ads returned (max 2000), or -1 for everything available. (default: 30)
pages number optional Pages of results to collect in one request (max 100), or -1 for the maximum allowed.
cursor string optional Resume from a previous response's nextCursor.
delayMs number optional Milliseconds to wait between pages (max 30000).
sortBy string optional start_date, end_date, total_active_time, or none.
sortDirection string optional asc or desc.
Response Fields
search-ads
Search ads by keyword
filters object The filters this search actually ran with, after defaults were applied.
ads object[] The matching ads, newest data first unless sortBy says otherwise.
ads[].adArchiveId string Ad Library archive id — the handle for ad-detail and ad-media.
ads[].adLibraryUrl string Public Ad Library permalink for this ad.
ads[].isActive boolean Whether the ad was still running when it was scraped.
ads[].startDate string First day the ad served impressions.
ads[].totalActiveTimeSeconds number How long the ad has been live — the usual proxy for what is working.
ads[].publisherPlatforms string[] Surfaces the ad ran on (Facebook, Instagram, Messenger, Threads…).
ads[].advertiser object Page id, name, URL, categories, like count, and political byline.
ads[].creative object Title, body, caption, link, CTA, display format, plus videos, images and carousel cards.
ads[].transparency object Spend, currency, impressions and reach bands for political and issue ads.
adCount number Number of ads in this response.
pagesScraped number Pages actually walked. Each page counts as one request against your plan.
nextCursor string Pass back as cursor to continue from where this response stopped.
hasNextPage boolean Whether more results are available beyond this response.
Request
curl -X POST "https://api.fetchlayer.dev/facebook-ad-library/search-ads" \
-H "Authorization: Bearer ss-your-key" \
-H "Content-Type: application/json" \
-d '{"query":"project management software","country":"US","activeStatus":"active","mediaType":"video","limit":30}'Response
{
"adCount": 30,
"pagesScraped": 1,
"hasNextPage": true,
"ads": [
{
"adArchiveId": "1234567890123456",
"isActive": true,
"startDate": "2026-07-14",
"publisherPlatforms": [
"FACEBOOK",
"INSTAGRAM"
],
"advertiser": {
"pageId": "987654321",
"pageName": "Acme Software"
},
"creative": {
"title": "Ship faster with Acme",
"ctaText": "Sign Up",
"linkUrl": "https://example.com"
}
}
]
}