# Facebook Ads Library \[From $0.3๐Ÿ’ฐ] Scraper \[Reach Included] PPE (`memo23/facebook-ads-library-scraper-ppe`) Actor \[From $0.3๐Ÿ’ฐ] Facebook Ads Library Scraper โ€” search the Meta Ad Library by keyword or page URL and export every ad: creatives, copy, spend & impressions, EU reach & transparency, advertiser pages, run dates. Richest schema on the Store. Filter by country, status & media type. - **URL**: https://apify.com/memo23/facebook-ads-library-scraper-ppe.md - **Developed by:** [Muhamed Didovic](https://apify.com/memo23) (community) - **Categories:** Social media, Agents, AI - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $0.30 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Facebook Ads Library Scraper **Scrape active Facebook ads with filters like keywords, dates, media type, and country** --- ### Overview This actor scrapes Facebook's Ads Library to extract detailed information about active advertising campaigns. Ideal for marketers, competitors, and researchers analyzing ad strategies. Supports filtering by: - Keywords/phrases (e.g., "free shipping") - Date ranges (up to 2025-02-15) - Media types (video/image/text) - Countries (e.g., GB for UK-targeted ads) - Ad status (active/inactive) --- ### Features - **๐Ÿ”Ž Keyword Search (no URL needed)**: Just enter search terms, countries, and status โ€” the actor builds the Meta Ad Library query for you. No hand-crafted URLs. - **Flexible URL Input**: Supports both Ads Library URLs and direct Facebook page URLs (e.g., `https://www.facebook.com/SHEINOFFICIAL`) - **Automatic Page ID Extraction**: Automatically extracts page IDs from Facebook page URLs and converts them to Ads Library format - **Precision Filtering**: Target ads by 10+ criteria including media type, country, and exact keywords - **Dynamic Delays**: Randomized delays (5-10s) between API calls to avoid detection - **Residential Proxies**: Built-in Apify residential proxy rotation - **Retry Resilience**: 100 retries per failed request - **Concurrency Control**: Process 1-10 pages simultaneously - **Historical Range**: Scrape ads up to future dates (2025-02-15 supported) --- ### How to Use 1. **Configure Input**: Set your filters in the input JSON (see configuration below) 2. **Run via Apify**: Execute the actor on Apify platform 3. **Export Data**: Download results as JSON, CSV, or Excel 4. **Analyze**: Track ad creatives, sponsors, and run dates --- ### Input Configuration #### Easiest โ€” Search by keyword (no URL needed) Just type what you want and the actor builds the Meta Ad Library query for you โ€” no need to hand-craft a URL. ```json { "searchTerms": ["nike", "weight loss"], "searchCountries": ["US", "GB"], "adActiveStatus": "active", "mediaType": "all", "searchMode": "keyword_unordered", "maxItems": 100, "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ```` | Field | What it does | |---|---| | `searchTerms` | Keywords or brand names โ€” each term is searched separately | | `searchCountries` | ISO 2-letter codes (`US`, `GB`, โ€ฆ) or `ALL`; each is queried per term | | `adActiveStatus` | `active`, `inactive`, or `all` | | `mediaType` | `all`, `image`, or `video` | | `searchMode` | `keyword_unordered` (broad โ€” any word) or `keyword_exact_phrase` (auto-quoted) | | `startDateMin` / `startDateMax` | Only ads that started in this date window (`YYYY-MM-DD`) | > Need political/housing/employment ad categories, a specific publisher platform, or a content language? Paste a full Ads Library URL via `startUrls` instead (see the advanced examples below). #### Example 1: Using Facebook Page URLs (Direct) ```json { "startUrls": [ "https://www.facebook.com/SHEINOFFICIAL", "https://www.facebook.com/Nike", "https://www.facebook.com/usemotionapp" ], "maxItems": 100, "minDelay": 5, "maxDelay": 10, "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ``` #### Example 2: Using Ads Library URLs (Advanced Filtering) ```json { "startUrls": [ "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=GB&is_targeted_country=false&media_type=video&q=%22free%20shipping%22&search_type=keyword_exact_phrase&start_date[min]&start_date[max]=2025-02-15", "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&view_all_page_id=103598131567301" ], "maxItems": 100, "minDelay": 5, "maxDelay": 10, "maxConcurrency": 10, "minConcurrency": 1, "maxRequestRetries": 100, "proxy": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] } } ``` ### Supported URL Formats The scraper accepts two types of URLs: #### 1. Direct Facebook Page URLs ``` https://www.facebook.com/SHEINOFFICIAL https://www.facebook.com/Nike https://www.facebook.com/usemotionapp ``` **How it works:** - The scraper automatically fetches the page with authentication - Extracts the page ID (e.g., `100064280965738` for SHEIN) - Converts to Ads Library URL format - Fetches all ads for that page #### 2. Facebook Ads Library URLs (with filters) ``` https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=GB&media_type=video&q=keyword https://www.facebook.com/ads/library/?active_status=all&search_type=page&view_all_page_id=123456 ``` **Benefits:** - Apply advanced filters (country, media type, keywords, date ranges) - Search by page ID directly - Filter by active/inactive status *** #### Input Parameters | Parameter | Type | Description | Default | |-----------|------|-------------|---------| | **startUrls** | Array | Facebook page URLs (e.g., `https://www.facebook.com/SHEINOFFICIAL`) or Ads Library URLs with filters | Required | | **maxItems** | Integer | Max ads to scrape per run | 100 | | **minDelay** | Integer | Minimum delay (seconds) between API calls | 5 | | **maxDelay** | Integer | Maximum delay (seconds) between API calls | 10 | | **maxConcurrency** | Integer | Max parallel page processing threads | 10 | | **minConcurrency** | Integer | Minimum parallel threads | 1 | | **maxRequestRetries** | Integer | Retry attempts for failed requests | 100 | | **proxy** | Object | Residential proxy configuration | Apify Proxy | *** ### Output Structure ```json { "FB AD Link": "https://www.facebook.com/ads/library/?id=554396010944539", "FB Link": "https://www.facebook.com/usemotionapp/", "Company Name": "Motion", "Website": "usemotion.com", "ad_archive_id": "554396010944539", "ad_id": null, "archive_types": [], "categories": [ "UNKNOWN" ], "collation_count": 3, "collation_id": "693850463625155", "contains_digital_created_media": false, "contains_sensitive_content": false, "currency": "", "end_date": 1750921200, "entity_type": "PERSON_PROFILE", "fev_info": null, "finserv_ad_data": null, "gated_type": "ELIGIBLE", "has_user_reported": false, "hidden_safety_data": false, "hide_data_status": "NONE", "impressions_with_index": { "impressions_text": null, "impressions_index": -1 }, "is_aaa_eligible": true, "is_active": true, "is_profile_page": false, "menu_items": [], "page_id": "103598131567301", "page_is_deleted": false, "page_name": "Motion", "political_countries": [], "publisher_platform": [ "FACEBOOK", "INSTAGRAM" ], "reach_estimate": null, "regional_regulation_data": { "finserv": { "is_deemed_finserv": false, "is_limited_delivery": false }, "tw_anti_scam": { "is_limited_delivery": false } }, "report_count": null, "snapshot": { "body": { "text": "Be 137% more productive." }, "branded_content": null, "brazil_tax_id": null, "byline": null, "caption": "usemotion.com", "cards": [], "cta_text": "Saznajte viลกe", "cta_type": "LEARN_MORE", "country_iso_code": null, "current_page_name": "Motion", "disclaimer_label": null, "display_format": "IMAGE", "event": null, "images": [ { "original_image_url": "https://scontent.fhan3-3.fna.fbcdn.net/v/t39.35426-6/502492793_1054293803317783_201280583862847808_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=79MpJoaVUG4Q7kNvwGzgwMb&_nc_oc=AdmiCbM4h7hHcjzS78hBXhh-kqbqOiyZbu5YcnjTmYi8fJyxiRCghxaZKOkyGakvKAg&_nc_zt=14&_nc_ht=scontent.fhan3-3.fna&_nc_gid=NsTWAzJgoGosAcGMska1iA&oh=00_AfOBxg0zBZE5I8h5tQ7QlqjO3BHFUqgBjNGOIwlhhhXnmQ&oe=6863D5BA", "resized_image_url": "https://scontent.fhan3-3.fna.fbcdn.net/v/t39.35426-6/502652905_549954111382058_5494539714617214349_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=11YsJKhHL9gQ7kNvwFQyF27&_nc_oc=AdmwIyTGYmabIQ3WHIslhtAT6bmK-pIkXvG6fem73EUvNaeqpRlhhRrs6w-ml-ufqI8&_nc_zt=14&_nc_ht=scontent.fhan3-3.fna&_nc_gid=NsTWAzJgoGosAcGMska1iA&oh=00_AfN41oyHr6YPW3Oq9j2P4jT45pOn01uFJHcFHeXyg51a7A&oe=6863D380", "watermarked_resized_image_url": "", "image_crops": [] } ], "is_reshared": false, "link_description": "Motion Teams | Automatically prioritize tasks, schedule meetings, and resolve calendar conflicts. Used by over 10k CEOs and professionals to improve focus, get more done, and streamline workday.", "link_url": "https://www.usemotion.com/teams", "page_categories": [ "Software" ], "page_entity_type": "PERSON_PROFILE", "page_id": "103598131567301", "page_is_deleted": false, "page_is_profile_page": false, "page_like_count": 41998, "page_name": "Motion", "page_profile_picture_url": "https://scontent.fhan4-5.fna.fbcdn.net/v/t39.35426-6/508816737_586512144117458_1442892662474165395_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=pC-2Jifxs-kQ7kNvwHYxKPV&_nc_oc=AdlONKKEnKB8H5DdW-UAjQiF6v_oiF5LX2Nu7VArJ_JATWPzqPzqwORlya5VUYCpafM&_nc_zt=14&_nc_ht=scontent.fhan4-5.fna&_nc_gid=NsTWAzJgoGosAcGMska1iA&oh=00_AfPizUrkt_Gl03E8xTDQCz3GBlbeCfXWC_Mkr_YRLNHjBQ&oe=6863E1F2", "page_profile_uri": "https://www.facebook.com/usemotionapp/", "root_reshared_post": null, "title": "AI Project Management", "videos": [], "additional_info": null, "ec_certificates": [], "extra_images": [], "extra_links": [], "extra_texts": [], "extra_videos": [] }, "spend": null, "start_date": 1750921200, "state_media_run_label": null, "targeted_or_reached_countries": [], "total_active_time": 71587, "data_reach": { "advertiser": { "page": { "about": { "text": "Motion increases productivity by 137%\n\nWith automation and AI that intelligently plan your day, sched" }, "is_delegate_page_with_linked_primary_profile": false, "id": "103598131567301" }, "ad_library_page_info": null }, "aaa_info": { "targets_eu": true, "location_audience": [ { "name": "Nizozemska", "num_obfuscated": 0, "type": "countries", "excluded": false }, { "name": "Njemaฤka", "num_obfuscated": 0, "type": "countries", "excluded": false } ], "gender_audience": "Svi", "age_audience": { "min": 18, "max": 65 }, "eu_total_reach": 16, "age_country_gender_reach_breakdown": [ { "country": "NL", "age_gender_breakdowns": [ { "age_range": "35-44", "male": 1, "female": 1, "unknown": null }, { "age_range": "55-64", "male": 1, "female": null, "unknown": null }, { "age_range": "18-24", "male": 1, "female": null, "unknown": null }, { "age_range": "25-34", "male": 1, "female": 1, "unknown": null } ] }, { "country": "DE", "age_gender_breakdowns": [ { "age_range": "55-64", "male": 2, "female": null, "unknown": null }, { "age_range": "18-24", "male": 1, "female": 3, "unknown": null }, { "age_range": "35-44", "male": null, "female": 4, "unknown": null } ] } ], "payer_beneficiary_data": [ { "payer": "Motion", "beneficiary": "Motion" } ], "has_violating_payer_beneficiary": false, "is_ad_taken_down": false }, "violation_types": [], "verified_voice_context": null, "transparency_by_location": null } } ``` #### **Basic Ad Information** | Field | Type | Description | |-------|------|-------------| | `FB AD Link` | String | Direct URL to ad in Facebook's Transparency Library | | `FB Link` | String | Permanent link to advertiser's Facebook profile/page | | `Company Name` | String | Registered name of advertising entity (matches page\_name) | | `Website` | String | Main website domain from the ad's link (e.g., usemotion.com) | *** #### **Ad Identification** | Field | Type | Description | |-------|------|-------------| | `ad_archive_id` | String | Facebook's internal archive identifier (unique per ad) | | `ad_id` | Null | Legacy field (deprecated by Facebook) | | `archive_types` | Array | Empty array in sample, used for ad classification | | `categories` | Array | Facebook's classification (e.g., `["UNKNOWN"]`) | | `collation_id` | String | Group ID for related ads in same campaign | | `collation_count` | Integer | Number of ads in this campaign group | | `page_id` | String | Unique Facebook ID of advertiser's page | *** #### **Ad Status & Timing** | Field | Type | Description | |-------|------|-------------| | `is_active` | Boolean | `true` = Currently running, `false` = Inactive | | `start_date` | Integer | Unix timestamp (seconds) of ad start date | | `end_date` | Integer | Unix timestamp (seconds) of planned end date | | `total_active_time` | Integer | Duration in seconds the ad has been active | | `is_aaa_eligible` | Boolean | Indicates if ad is eligible for automated ads | *** #### **Ad Content & Format** | Field | Type | Description | |-------|------|-------------| | `snapshot.body.text` | String | Full text content of ad | | `snapshot.title` | String | Headline/title of ad | | `snapshot.display_format` | String | `IMAGE` for static image ads | | `snapshot.cta_text` | String | Call-to-action button text (e.g., "Saznajte viลกe") | | `snapshot.cta_type` | String | Type of CTA (e.g., "LEARN\_MORE") | | `snapshot.link_url` | String | Destination URL when clicking ad | | `snapshot.link_description` | String | Description text shown in link preview | | `snapshot.images` | Array | Array containing image objects with URLs | | `snapshot.images[].original_image_url` | String | Full resolution image URL | | `snapshot.images[].resized_image_url` | String | Resized version of the image | | `snapshot.videos` | Array | Empty array for non-video ads | *** #### **Page/Advertiser Insights** | Field | Type | Description | |-------|------|-------------| | `page_name` | String | Name of Facebook page running ad | | `page_like_count` | Integer | Total page followers/likes | | `page_profile_picture_url` | String | Current profile image URL | | `page_profile_uri` | String | Direct link to page profile | | `page_categories` | Array | Facebook's business classification (e.g., `["Software"]`) | | `page_entity_type` | String | Type of page (e.g., `PERSON_PROFILE`) | | `page_is_deleted` | Boolean | Indicates if the page has been deleted | | `page_is_profile_page` | Boolean | Indicates if this is a personal profile page | *** #### **Technical Metadata** | Field | Type | Description | |-------|------|-------------| | `entity_type` | String | `PERSON_PROFILE` (individual) or `BUSINESS` | | `publisher_platform` | Array | Platforms where ad appears (e.g., `["FACEBOOK", "INSTAGRAM"]`) | | `contains_digital_created_media` | Boolean | `false` if contains only original media | | `gated_type` | String | Age/gender gating status (e.g., `ELIGIBLE`) | | `hide_data_status` | String | `NONE` = Full visibility | | `is_reshared` | Boolean | `false` if this is an original post | *** #### **Compliance & Regulations** | Field | Type | Description | |-------|------|-------------| | `political_countries` | Array | Empty array in sample, indicates countries where ad is political | | `regional_regulation_data` | Object | Contains compliance flags | | `regional_regulation_data.finserv` | Object | Financial services compliance data | | `regional_regulation_data.finserv.is_deemed_finserv` | Boolean | If ad is considered financial service | | `regional_regulation_data.finserv.is_limited_delivery` | Boolean | If ad has delivery restrictions | | `regional_regulation_data.tw_anti_scam` | Object | Taiwan anti-scam regulations | | `state_media_run_label` | Null | For government-affiliated ads | *** #### **User Interaction Data** | Field | Type | Description | |-------|------|-------------| | `report_count` | Null | Number of user reports (restricted) | | `has_user_reported` | Boolean | `false` if current user hasn't reported the ad | | `finserv_ad_data` | Null | Financial service ad data (restricted) | | `fev_info` | Null | Fact-checking verification data | *** #### **Monetization & Reach** | Field | Type | Description | |-------|------|-------------| | `spend` | Null | Ad budget (restricted) | | `reach_estimate` | Null | Potential audience size (restricted) | | `currency` | String | Empty string when spend data is restricted | | `impressions_with_index` | Object | Contains impression data | | `impressions_with_index.impressions_text` | Null | Formatted impressions text | | `impressions_with_index.impressions_index` | Integer | -1 when data is restricted | *** #### **System Flags** | Field | Type | Description | |-------|------|-------------| | `contains_sensitive_content` | Boolean | `false` if content is not flagged as sensitive | | `hidden_safety_data` | Boolean | `false` if no safety restrictions are applied | | `is_profile_page` | Boolean | `false` if not a profile page ad | | `menu_items` | Array | Empty array in sample | *** #### **Audience & Targeting** | Field | Type | Description | |-------|------|-------------| | `targeted_or_reached_countries` | Array | Empty array in sample | | `data_reach` | Object | Detailed audience reach data | | `data_reach.advertiser` | Object | Information about the advertiser | | `data_reach.advertiser.page.about.text` | String | Page description text | | `data_reach.aaa_info` | Object | Detailed audience analytics | | `data_reach.aaa_info.targets_eu` | Boolean | `true` if targeting EU countries | | `data_reach.aaa_info.location_audience` | Array | Targeted locations | | `data_reach.aaa_info.gender_audience` | String | Targeted gender (e.g., "Svi" for all) | | `data_reach.aaa_info.age_audience` | Object | `{min, max}` age range | | `data_reach.aaa_info.eu_total_reach` | Integer | Estimated reach in EU | | `data_reach.aaa_info.age_country_gender_reach_breakdown` | Array | Detailed breakdown by country, age, and gender | *** ### Key Notes 1. **Timestamps**: Convert Unix timestamps (e.g., `1750921200` โ†’ `2025-02-24T23:00:00Z`) 2. **Null Fields**: Indicate restricted data per Facebook's policies 3. **Media URLs**: May expire - download promptly 4. **Audience Data**: Includes detailed demographic breakdowns when available 5. **Compliance**: Contains regulatory information for different regions Key fields include: - Ad creative (text/images/video URLs) - Sponsor page details and metrics - Detailed audience targeting information - Active dates and duration - Compliance and regulation data - Call-to-action configuration *** ### Why This Scraper? - **Compliance**: Follows Facebook's rate limits and robots.txt - **Stealth**: Residential proxies + random delays mimic human behavior - **Depth**: Captures 30+ data points per ad including edits history - **Future-Proof**: Handles Facebook's frequent UI/API changes *** ### Use Cases - Track competitor ad strategies in real-time - Analyze seasonal campaign patterns - Archive political ads for transparency - Monitor trademark violations *** ### Explore More Scrapers If you found this Apify Smartbuyglasses Scraper useful, be sure to check out our other powerful scrapers and actors at [memo23's Apify profile](https://apify.com/memo23). We offer a wide range of tools to enhance your web scraping and automation needs across various platforms and use cases. ### Support - For issues or feature requests, please use the [Issues](https://console.apify.com/actors/3853UUZQG6pjjdw11/issues) section of this actor. - If you need customization or have questions, feel free to contact the author: - Author's website: - Email: ### Additional Services - Request customization or whole dataset: - If you need anything else scraped, or this actor customized, email: - For API services of this scraper (no Apify fee, just usage fee for the API), contact: - Email: muhamed.didovic@gmail.com # Actor input Schema ## `startUrls` (type: `array`): Paste full Meta Ad Library URLs (with any filters) or Facebook Page URLs. This is the most powerful mode โ€” it supports every Ad Library filter (country, media type, status, keyword/phrase, date range, political/housing/employment categories, publisher platform, language). Example: https://www.facebook.com/ads/library/?active\_status=active\&ad\_type=all\&country=US\&is\_targeted\_country=false\&media\_type=all\&q=nike\&search\_type=keyword\_unordered โ€” or a page URL like https://www.facebook.com/Nike. ## `searchTerms` (type: `array`): Keywords or brand names to look up in the Meta Ad Library โ€” e.g. nike, weight loss, black friday. Each term is searched separately. Leave empty if you're pasting URLs above. The fields below apply to these search terms. ## `searchCountries` (type: `array`): Two-letter country codes (US, GB, DE โ€ฆ) or ALL for worldwide. Each country is queried separately per search term. Defaults to US. ## `adActiveStatus` (type: `string`): Filter by whether ads are currently running. ## `mediaType` (type: `string`): Filter ads by creative media type. ## `searchMode` (type: `string`): Broad matches any of the words; Exact phrase matches the words together (auto-wrapped in quotes). ## `startDateMin` (type: `string`): Only include ads that started running on or after this date. Format YYYY-MM-DD. Leave empty to skip. ## `startDateMax` (type: `string`): Only include ads that started running on or before this date. Format YYYY-MM-DD. Leave empty to skip. ## `includeAdReach` (type: `boolean`): Include Ad Reach and EU transparency in output. ## `includeTotalActiveAds` (type: `boolean`): Include total active ads count per page in output. ## `filterDuplicatePageIds` (type: `boolean`): If enabled, only one ad per unique page\_id will be kept (first occurrence). This removes duplicate ads from the same page. ## `categories` (type: `array`): You can add one more categories to filter ads by their categories like: brand, etc. Write one category per input/line. ## `maxItems` (type: `integer`): Maximum number of items that will be scraped per crawl. ## `minDelay` (type: `integer`): Minimum delay to wait before calling the new items from API. ## `maxDelay` (type: `integer`): Maximum delay to wait before calling the new items from API ## `maxConcurrency` (type: `integer`): Maximum number of pages that can be processed at the same time. ## `minConcurrency` (type: `integer`): Minimum number of pages that will be processed at the same time. ## `maxRequestRetries` (type: `integer`): Number of times the crawler will retry a failed request before giving up. ## `proxy` (type: `object`): Specifies proxy servers that will be used by the scraper in order to hide its origin.

For details, see Proxy configuration in README. ## `debug` (type: `boolean`): If enabled, the actor will output detailed debug logs including proxy info, session details, response headers, and content structure analysis. Useful for troubleshooting. ## Actor input object example ```json { "startUrls": [ "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&is_targeted_country=false&media_type=all&q=nike&search_type=keyword_unordered" ], "searchTerms": [], "searchCountries": [ "US" ], "adActiveStatus": "active", "mediaType": "all", "searchMode": "keyword_unordered", "startDateMin": "", "startDateMax": "", "includeAdReach": false, "includeTotalActiveAds": false, "filterDuplicatePageIds": false, "categories": [], "maxItems": 10000, "minDelay": 5, "maxDelay": 10, "maxConcurrency": 10, "minConcurrency": 1, "maxRequestRetries": 100, "proxy": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] }, "debug": false } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "startUrls": [ "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&is_targeted_country=false&media_type=all&q=nike&search_type=keyword_unordered" ], "searchTerms": [], "searchCountries": [ "US" ], "categories": [], "proxy": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("memo23/facebook-ads-library-scraper-ppe").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startUrls": ["https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&is_targeted_country=false&media_type=all&q=nike&search_type=keyword_unordered"], "searchTerms": [], "searchCountries": ["US"], "categories": [], "proxy": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("memo23/facebook-ads-library-scraper-ppe").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "startUrls": [ "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&is_targeted_country=false&media_type=all&q=nike&search_type=keyword_unordered" ], "searchTerms": [], "searchCountries": [ "US" ], "categories": [], "proxy": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call memo23/facebook-ads-library-scraper-ppe --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=memo23/facebook-ads-library-scraper-ppe", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Facebook Ads Library [From $0.3๐Ÿ’ฐ] Scraper [Reach Included] PPE", "description": "[From $0.3๐Ÿ’ฐ] Facebook Ads Library Scraper โ€” search the Meta Ad Library by keyword or page URL and export every ad: creatives, copy, spend & impressions, EU reach & transparency, advertiser pages, run dates. Richest schema on the Store. Filter by country, status & media type.", "version": "0.0", "x-build-id": "Xes73dG7LBHTVnZ55" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/memo23~facebook-ads-library-scraper-ppe/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-memo23-facebook-ads-library-scraper-ppe", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/memo23~facebook-ads-library-scraper-ppe/runs": { "post": { "operationId": "runs-sync-memo23-facebook-ads-library-scraper-ppe", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/memo23~facebook-ads-library-scraper-ppe/run-sync": { "post": { "operationId": "run-sync-memo23-facebook-ads-library-scraper-ppe", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "startUrls": { "title": "Start URLs", "maxItems": 5, "type": "array", "description": "Paste full Meta Ad Library URLs (with any filters) or Facebook Page URLs. This is the most powerful mode โ€” it supports every Ad Library filter (country, media type, status, keyword/phrase, date range, political/housing/employment categories, publisher platform, language). Example: https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&is_targeted_country=false&media_type=all&q=nike&search_type=keyword_unordered โ€” or a page URL like https://www.facebook.com/Nike.", "items": { "type": "string" } }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords or brand names to look up in the Meta Ad Library โ€” e.g. nike, weight loss, black friday. Each term is searched separately. Leave empty if you're pasting URLs above. The fields below apply to these search terms.", "items": { "type": "string" } }, "searchCountries": { "title": "Countries (ISO 2-letter codes)", "type": "array", "description": "Two-letter country codes (US, GB, DE โ€ฆ) or ALL for worldwide. Each country is queried separately per search term. Defaults to US.", "items": { "type": "string" } }, "adActiveStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Filter by whether ads are currently running.", "default": "active" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video" ], "type": "string", "description": "Filter ads by creative media type.", "default": "all" }, "searchMode": { "title": "Keyword match", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "Broad matches any of the words; Exact phrase matches the words together (auto-wrapped in quotes).", "default": "keyword_unordered" }, "startDateMin": { "title": "Started on or after (YYYY-MM-DD)", "type": "string", "description": "Only include ads that started running on or after this date. Format YYYY-MM-DD. Leave empty to skip.", "default": "" }, "startDateMax": { "title": "Started on or before (YYYY-MM-DD)", "type": "string", "description": "Only include ads that started running on or before this date. Format YYYY-MM-DD. Leave empty to skip.", "default": "" }, "includeAdReach": { "title": "Include Ad Reach and EU transparency in output", "type": "boolean", "description": "Include Ad Reach and EU transparency in output.", "default": false }, "includeTotalActiveAds": { "title": "Include total active ads count per page in output", "type": "boolean", "description": "Include total active ads count per page in output.", "default": false }, "filterDuplicatePageIds": { "title": "Filter duplicate page IDs", "type": "boolean", "description": "If enabled, only one ad per unique page_id will be kept (first occurrence). This removes duplicate ads from the same page.", "default": false }, "categories": { "title": "Filter ads by categories", "type": "array", "description": "You can add one more categories to filter ads by their categories like: brand, etc. Write one category per input/line.", "items": { "type": "string" } }, "maxItems": { "title": "Maximum items per crawl", "type": "integer", "description": "Maximum number of items that will be scraped per crawl.", "default": 10000 }, "minDelay": { "title": "Min delay for API call", "type": "integer", "description": "Minimum delay to wait before calling the new items from API.", "default": 5 }, "maxDelay": { "title": "Max delay for API call", "type": "integer", "description": "Maximum delay to wait before calling the new items from API", "default": 10 }, "maxConcurrency": { "title": "Max Concurrency", "type": "integer", "description": "Maximum number of pages that can be processed at the same time.", "default": 10 }, "minConcurrency": { "title": "Min Concurrency", "type": "integer", "description": "Minimum number of pages that will be processed at the same time.", "default": 1 }, "maxRequestRetries": { "title": "Max Request Retries", "type": "integer", "description": "Number of times the crawler will retry a failed request before giving up.", "default": 100 }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "Specifies proxy servers that will be used by the scraper in order to hide its origin.

For details, see Proxy configuration in README.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "debug": { "title": "Enable Debug Logging", "type": "boolean", "description": "If enabled, the actor will output detailed debug logs including proxy info, session details, response headers, and content structure analysis. Useful for troubleshooting.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```