Facebook: Ads
facebook_adsMeta Ads Library: search ads, find advertisers by keyword, advertiser page details, single ad details and supported countries.
Actions:
action=search: Search ads in the Meta Ad Library. Pass a keyword (query) to find ads about a topic, or ad_page_id to list one advertiser's ads; filter by country, active status and date range, sort by impressions or recency. Returns ads with creative, body text, dates, platforms and snapshot URL, plus an end_cursor. Get an advertiser's ad_page_id from action=keywords or facebook_page (action=details). Pricing: 1 credit per call. Inputs: query (optional), ad_page_id (optional), country (optional), activeStatus (optional), after_time (optional), before_time (optional), sort_data (optional), end_cursor (optional).
action=keywords: Find advertisers running ads that match a keyword: returns Facebook pages with their page_id and ad count. Use it to discover who advertises on a topic, then pass a page_id to action=search (as ad_page_id) or action=page_details. To get the ads for a keyword directly, use action=search. Pricing: 1 credit per call. Inputs: query (required), country (optional).
action=page_details: Get an advertiser's Ads Library profile: page name, verification status, category, location and total ad count. Needs the page ID (ad_page_id from facebook_page (action=details) or page_id from action=keywords). To list the ads themselves, use action=search with ad_page_id. Pricing: 1 credit per call. Inputs: page_id (required).
action=archive_details: Get one Ad Library ad in full: creative, body text, CTA, platforms, countries, date range, and spend and impression estimates where Meta publishes them. Needs the ad_archive_id from a action=search result. Pricing: 1 credit per call. Inputs: ad_archive_id (required), page_id (optional), country (optional), is_ad_non_political (optional), is_ad_not_aaa_eligible (optional).
action=countries: List the country codes the Ads Library tools accept in their country parameter. Pricing: 1 credit per call. Inputs: none.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Keyword. search: words in the ads (or pass ad_page_id instead) · keywords: a topic to find advertisers for, e.g. running shoes. Required for: keywords. Optional for: search. | |
| action | Yes | Which operation to run. See the tool description for what each action returns and which parameters it needs. | |
| country | No | ISO country code or "ALL". Optional for: search, keywords, archive_details. | |
| page_id | No | Advertiser page ID: ad_page_id from facebook_page (action=details), or page_id from action=keywords. Required for: page_details. Optional for: archive_details. | |
| sort_data | No | Sort by "impressions" or "recent". Optional for: search. | |
| ad_page_id | No | Facebook AD Page ID (alternative to query). Optional for: search. | |
| after_time | No | Filter ads after this date (YYYY-MM-DD). Optional for: search. | |
| end_cursor | No | Pagination cursor. Optional for: search. | |
| before_time | No | Filter ads before this date (YYYY-MM-DD). Optional for: search. | |
| activeStatus | No | Filter: ALL, Active, or Inactive. Optional for: search. | |
| ad_archive_id | No | Ad Library archive ID of the ad (ad_archive_id from a action=search result). Required for: archive_details. | |
| is_ad_non_political | No | Filter non-political ads. Optional for: archive_details. | |
| is_ad_not_aaa_eligible | No | Filter AAA eligibility. Optional for: archive_details. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes | JSON response from the SocialAPIs REST endpoint, unchanged. Object or array depending on the endpoint; most include a `meta` block (statusCode, duration, creditsCharged, creditsRemaining). | |
| creditsCharged | No | Credits charged for this call, or null if the endpoint did not report it. | |
| creditsRemaining | No | Credits left on the API key after this call, or null if not reported. |