facebook_ad_library_search
Search Meta Ad Library by keyword — active/inactive, media type, date range, platforms, cursor, and spend/impressions when Meta publishes them. Each ad has creativeHash + landingDomain; dedupe=true merges repeats. Costs 2 credits. Empty results and failures are never charged. Pass cache=true for a free 24h cache hit (default always fresh).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"q": "<q>"
},
"name": "facebook_ad_library_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Keyword, brand, or advertiser to search Meta Ad Library (min 2 characters). | |
| trim | No | When true, omit cards/images/videos typed arrays (media[] stays). Captapi payloads are already lean vs Meta nested snapshots. | |
| cache | No | Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. | |
| limit | No | Max items to return (default 20, max 200). Flat 2 credits per call. | |
| cursor | No | Pagination cursor from a previous nextCursor. Pages through the current Meta HTML result batch. | |
| dedupe | No | When true, ads with the same creativeHash (same copy, headline and landing domain) collapse into one row, the first in library order, with duplicateIds[] (every ad id in the group) and duplicateCount (group size). Duplicates are merged only among the ads this request fetched (retrievableCount). Ads from another request or from library pages past this batch are not compared, so the same creative can appear again there. Default false: every ad is its own row and no duplicate fields are added. Same price. | |
| fields | No | Optional comma-separated keys to keep on each result row (or on the object for single-item tools), e.g. id,url,publishedAt,engagement. Pagination keys are always kept. Does not change the price. | |
| status | No | Ad delivery status: ACTIVE (default), INACTIVE, or ALL. Use ACTIVE for "what are they running now?". | |
| ad_type | No | all (default) or political_and_issue_ads. Spend/impressions are typically only filled for political/issue ads. | |
| compact | No | Default true here: drop signed media URLs (video, image, avatar links and their expiry stamps) to keep the response small. Ids, permalinks, dates, text and metrics stay. On Threads, Facebook, Meta Ad Library and TikTok Shop tools request timings are dropped too. Pass false for the full body. | |
| country | No | Two-letter ISO country code (e.g. US, GB, DE), or ALL for every country (Meta's own value). Default US. For inactive ads prefer ALL: a single-country search can list far fewer inactive ads than ALL. Other non-ISO codes are a definitive 400 INVALID_COUNTRY — Meta would otherwise ignore the code and search globally while echoing it back as if the filter worked. | |
| sort_by | No | Meta sort mode: total_impressions or relevancy_monthly_grouped. | |
| end_date | No | Only ads shown (delivered) on or before this date (YYYY-MM-DD). | |
| platforms | No | Comma-separated publisher platforms to keep: FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, THREADS. | |
| media_type | No | Creative filter: ALL (default), IMAGE, VIDEO, MEME, IMAGE_AND_MEME, or NONE. | |
| start_date | No | Only ads shown (delivered) on or after this date (YYYY-MM-DD). Delivery-date window, not a start-date filter: an ad that started earlier but was still running in the range is included. | |
| search_type | No | keyword_unordered (default) or keyword_exact_phrase. |