search_ads_archive
Search Facebook Ads Library by keyword and country to access ad creatives, spend, impressions, and delivery details for transparency and competitive research.
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"
Input Schema
TableJSON 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
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |