search_ads_archive
Search the Meta Ads Library archive to retrieve ads by type, region, or keywords. Analyze ad content, spending, and demographics for Facebook and Instagram campaigns.
Instructions
Search the Facebook Ads Library archive.
Args:
access_token: Meta API access token (optional - will use cached token if not provided).
search_terms: The search query for ads.
ad_type: Type of ads to search for (e.g., POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, ALL).
ad_reached_countries: List of country codes (e.g., ["US", "GB"]).
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"
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| access_token | No | ||
| ad_reached_countries | No | ||
| ad_type | No | ALL | |
| 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 | |
| limit | No | ||
| search_terms | No |
Input Schema (JSON Schema)
{
"properties": {
"access_token": {
"default": null,
"title": "Access Token",
"type": "string"
},
"ad_reached_countries": {
"default": null,
"items": {
"type": "string"
},
"title": "Ad Reached Countries",
"type": "array"
},
"ad_type": {
"default": "ALL",
"title": "Ad Type",
"type": "string"
},
"fields": {
"default": "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",
"title": "Fields",
"type": "string"
},
"limit": {
"default": 25,
"title": "Limit",
"type": "integer"
},
"search_terms": {
"default": null,
"title": "Search Terms",
"type": "string"
}
},
"title": "search_ads_archiveArguments",
"type": "object"
}