search_ads_archive
Search the Facebook Ads Library archive by keywords and countries to find ads, filter by ad type, and retrieve fields like spend and impressions.
Instructions
Search the Facebook Ads Library archive.
Args:
search_terms: The search query for ads.
ad_reached_countries: List of country codes (e.g., ["US", "GB"]).
access_token: Meta API access token (optional - will use cached token if not provided).
ad_type: Type of ads to search for (e.g., POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, ALL).
limit: Maximum number of ads to return.
fields: Comma-separated string of fields to retrieve for each ad.
Example Usage via curl equivalent:
curl -G \
-d "search_terms='california'" \
-d "ad_type=POLITICAL_AND_ISSUE_ADS" \
-d "ad_reached_countries=['US']" \
-d "fields=ad_snapshot_url,spend" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/ads_archive"
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": {
"search_terms": "<search_terms>",
"ad_reached_countries": "<ad_reached_countries>"
},
"name": "search_ads_archive"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| fields | No | ad_creation_time,ad_creative_body,ad_creative_link_caption,ad_creative_link_description,ad_creative_link_title,ad_delivery_start_time,ad_delivery_stop_time,ad_snapshot_url,currency,demographic_distribution,funding_entity,impressions,page_id,page_name,publisher_platform,region_distribution,spend | |
| ad_type | No | ALL | |
| access_token | No | ||
| search_terms | Yes | ||
| ad_reached_countries | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |