search_facebook_ads
Read-only
Search the Facebook Ads Library for live ads by keywords, brand names, or filters. Returns compact previews with an option to retrieve full results from a saved file.
Instructions
Search the Facebook Ads Library for live ads matching the given queries.
Runs a remote scraper (30s–few minutes). Full results are saved to a JSON file; only a compact preview is returned inline. Use read_saved_results to page through the full dataset without flooding context.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ad_type | No | Ad type filter: ALL, POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS, or CREDIT_ADS. | ALL |
| country | No | ISO country code to filter by, e.g. 'US', 'IN', or 'ALL'. None for no filter. | |
| sort_by | No | Sort order: SORT_BY_TOTAL_IMPRESSIONS or SORT_BY_RELEVANCY_MONTHLY_GROUPED. | SORT_BY_TOTAL_IMPRESSIONS |
| end_date | No | Latest ad delivery date in YYYY-MM-DD format. None for no upper bound. | |
| media_type | No | Media type filter: ALL, IMAGE, MEME, IMAGE_AND_MEME, VIDEO, or NONE. | ALL |
| start_date | No | Earliest ad delivery date in YYYY-MM-DD format. None for no lower bound. | |
| active_status | No | Ad status filter: ALL, ACTIVE, or INACTIVE. | ALL |
| search_queries | Yes | Keywords or brand names to search for, e.g. ['nike', 'adidas']. | |
| content_languages | No | Language codes to filter ad content by, e.g. ['en', 'fr']. | |
| publisher_platforms | No | Platforms to filter by, e.g. ['facebook', 'instagram']. | |
| max_results_per_query | No | Maximum ads to return per query. Minimum 10 (actor limit). | |
| enrich_with_ad_details | No | Fetch extra per-ad details. Slower and uses more Apify credits. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ads | Yes | ||
| queries | Yes | ||
| file_path | Yes | ||
| result_count | Yes |