search_ads
Search the public Meta Ad Library for ads by keyword or advertiser across Facebook, Instagram, Messenger, Threads and Audience Network, with filters for country, status, dates and media type.
Instructions
Search the public Meta Ad Library (Facebook, Instagram, Messenger, Audience Network, Threads) for ads by keyword and/or advertiser.
Cost: 1 credit per 10 ads returned, rounded up (limit=10 → 1 credit, limit=50 → 5);
an empty result or an error costs 0. Keep limit small unless the user needs more.
Args: query: Keyword or phrase (1-100 chars). Required unless page_id is given. page_id: Restrict to one advertiser (numeric page ID, see search_pages). country: ISO-3166 alpha-2 country where the ads ran (e.g. 'IT', 'US') or 'ALL'. status: 'active' (default), 'inactive' or 'all'. ad_type: 'all' or 'political' (political & issue ads, with spend/impressions). media_type: 'all', 'image', 'video', 'meme' or 'none'. platforms: Subset of facebook, instagram, messenger, audience_network, threads. languages: ISO-639-1 language codes of the ad text (e.g. ['it', 'en']). active_from: YYYY-MM-DD; ads running at some point from this date. active_to: YYYY-MM-DD; ads running at some point up to this date. match: 'any' (all words, default) or 'exact' (exact phrase). sort: 'relevance' (default) or 'impressions' (most impressions first). limit: Ads per page, 1-50 (default 10). cursor: next_cursor from a previous call, to get the next page (same filters).
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "search_ads"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | relevance | |
| limit | No | ||
| match | No | any | |
| query | No | ||
| cursor | No | ||
| status | No | active | |
| ad_type | No | all | |
| country | No | ALL | |
| page_id | No | ||
| active_to | No | ||
| languages | No | ||
| platforms | No | ||
| media_type | No | all | |
| active_from | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |