{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Scraper Pro", "description": "Extract Facebook Ad Library data: creatives, targeting & metrics. $0.40 = 1,000 Successful Ad scrapeds * cheaper & more complete. ๐Ÿ“ฑ", "version": "0.3", "x-build-id": "7MbiPRvyd3HRG0hk3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dz_omar~facebook-ads-scraper-pro/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dz_omar-facebook-ads-scraper-pro", "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/dz_omar~facebook-ads-scraper-pro/runs": { "post": { "operationId": "runs-sync-dz_omar-facebook-ads-scraper-pro", "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/dz_omar~facebook-ads-scraper-pro/run-sync": { "post": { "operationId": "run-sync-dz_omar-facebook-ads-scraper-pro", "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": { "URLAds": { "title": "๐Ÿ”— Facebook Ad Library URLs (optional)", "type": "array", "description": "Paste Facebook Ad Library URLs to scrape directly. The actor will parse each URL and run the search automatically. If provided, URLs are processed first, followed by any Search Keywords and Advertisers below.\n\n**๐Ÿ’ก How it works:**\n- Copy a URL from [Facebook Ad Library](https://www.facebook.com/ads/library/) and paste it here\n- All filters from the URL (country, language, date range, media type, etc.) are extracted automatically\n- `Max Results Per Search` controls how many ads are collected per URL\n- You can mix URLs with manual search fields โ€” all run sequentially\n\n**๐Ÿ“Œ Single ad links supported:**\n- URLs like `?id=xxxxxxxxxxxx` will fetch that specific ad directly\n- Works with the enrichment toggle to get full ad details", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "searchQueries": { "title": "๐Ÿ” Search Keywords", "type": "array", "description": "**Search terms to find Facebook ads** ๐ŸŽฏ\n\nEnter keywords, phrases, or brand names to search for in Facebook's Ad Library:\n\n**Examples:**\n- Brand names: \"Nike\", \"Apple\", \"Coca-Cola\"\n- Product categories: \"fitness app\", \"crypto wallet\", \"online course\"\n- Industry terms: \"digital marketing\", \"e-commerce\", \"SaaS\"\n- Campaign themes: \"Black Friday\", \"back to school\", \"summer sale\"\n\n**๐Ÿ’ก Tips:**\n- Use specific terms for better results\n- Mix broad and specific keywords\n- Each query runs separately and results are combined\n- Empty queries will be skipped", "items": { "type": "string" } }, "searchAdvertisers": { "title": "๐Ÿข Search Advertisers", "type": "array", "description": "**Search by specific advertiser/page names or Page IDs** ๐ŸŽฏ\n\nEnter advertiser names or Facebook Page IDs to fetch ads from specific pages:\n\n**Examples:**\n- Advertiser names: \"Nike\", \"Nike Football\", \"Apple\"\n- Page IDs: \"15087023444\", \"51212153078\"\n- Mixed: [\"Nike\", \"15087023444\"]\n\n**๐Ÿ’ก How it works:**\n- **Name match**: If you enter \"Nike Football\", the scraper will find ALL Facebook pages with exactly that name and fetch ads from each\n- **Page ID**: If you enter a numeric ID like \"15087023444\", it goes directly to that page\n- **Multiple matches**: Some names like \"Nike Football\" may match multiple pages - ads will be fetched from ALL matching pages\n\n**โš ๏ธ Important:**\n- Each advertiser query uses your `maxResultsPerQuery` limit **per matching page**\n- Example: \"Nike Football\" matches 3 pages + maxResults=100 = 300 ads total\n- Names must match exactly (case-insensitive)\n\n**๐Ÿ” Tips:**\n- Use specific names for better matching\n- Check Facebook Ad Library to verify exact page names\n- Use Page IDs for precise targeting\n- Leave empty to skip advertiser search", "items": { "type": "string" } }, "maxResultsPerQuery": { "title": "๐Ÿ“Š Max Results Per Search", "minimum": 10, "type": "integer", "description": "**Maximum ads to collect per search** ๐Ÿ“ˆ\n\nThis limit applies to **every search source** in your run:\n- ๐Ÿ“Œ **Per URL** โ€” each Ad Library URL collects up to this many ads\n- ๐Ÿ” **Per keyword** โ€” each search query collects up to this many ads\n- ๐Ÿข **Per advertiser page** โ€” each resolved advertiser page collects up to this many ads\n\n**Example:** 2 URLs + 3 keywords + 2 advertisers with `maxResultsPerQuery = 50`\nโ†’ Up to 50 ads ร— 7 sources = up to **350 ads total**\n\n- **Default: 10** โ€” Good for quick tests\n- **50โ€“200** โ€” Recommended for most use cases\n- **๐Ÿ’ก Note:** Actual results may be lower if Facebook has fewer matching ads", "default": 10 }, "enrichWithAdDetails": { "title": "๐Ÿ” Enrich with Ad Details", "type": "boolean", "description": "**Fetch full ad details for each result** ๐Ÿ“Š\n\nWhen enabled, the scraper makes an additional request per ad to fetch rich advertiser and targeting data:\n\n**Extra data included:**\n- ๐Ÿข **Advertiser info**: page about text, category, likes, profile photo, cover photo, verification status\n- ๐Ÿ“ท **Instagram**: username, followers, verification\n- ๐ŸŽฏ **Targeting (EU)**: location audience, age/gender breakdown, total reach\n- ๐Ÿ’ฐ **Payer/Beneficiary**: who paid for and benefits from the ad\n- โš ๏ธ **Violations**: any policy violation types\n\n**โš ๏ธ Note:** Enabling this will slow down scraping since each ad requires an extra API call. Recommended for smaller result sets (< 200 ads).", "default": false }, "sortBy": { "title": "๐Ÿ“Š Sort Results By", "enum": [ "SORT_BY_TOTAL_IMPRESSIONS", "SORT_BY_RELEVANCY_MONTHLY_GROUPED" ], "type": "string", "description": "**Order search results** ๐Ÿ“ˆ\n\n- **Impressions (High to Low)**: Most viewed ads first (recommended)\n- **Most Recent**: Newest ads first\n\n**๐Ÿ’ก Tip:** Sort by impressions to see the most successful/popular ads", "default": "SORT_BY_TOTAL_IMPRESSIONS" }, "countries": { "title": "๐ŸŒ Target Countries", "enum": [ "ALL", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CK", "CR", "CI", "HR", "CU", "CW", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KP", "KR", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "SD", "SR", "SJ", "SZ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VI", "WF", "EH", "YE", "ZM", "ZW", "AF" ], "type": "string", "description": "**Filter ads by country targeting** ๐Ÿ—บ๏ธ\n\n**Popular Options:**\n- **US** - United States (largest ad market)\n- **CA** - Canada\n- **GB** - United Kingdom\n- **AU** - Australia\n- **DE** - Germany\n- **FR** - France\n- **ES** - Spain\n- **IT** - Italy\n- **BR** - Brazil\n- **IN** - India\n- **JP** - Japan\n\n**๐Ÿ’ก Use ISO 2-letter country codes** (e.g., US, CA, GB)" }, "contentLanguages": { "title": "๐Ÿ—ฃ๏ธ Content Languages", "type": "array", "description": "**Filter ads by content language** ๐Ÿ”ค\n\n**Common Languages:**\n- **en** - English\n- **es** - Spanish\n- **fr** - French\n- **de** - German\n- **it** - Italian\n- **pt** - Portuguese\n- **ja** - Japanese\n- **ko** - Korean\n- **zh** - Chinese\n- **ar** - Arabic\n\n**๐Ÿ’ก Use ISO 2-letter language codes**", "items": { "type": "string", "enum": [ "", "en", "es", "fr", "de", "it", "pt", "ja", "ko", "zh", "ar", "ru", "hi", "tr", "pl", "nl", "sv", "da", "no", "fi", "el", "he", "th", "vi", "id", "ms", "tl", "uk", "cs", "sk", "hu", "ro", "bg", "hr", "sr", "sl", "et", "lv", "lt", "mt", "ga", "cy", "is", "fo", "lb", "rm", "eu", "ca", "gl", "oc", "br", "kw", "gd", "gv", "nn", "se", "be", "mk", "sq", "bs", "me", "xk", "sm", "ad", "li", "mc", "va" ], "enumTitles": [ "All languages ๐ŸŒ", "English ๐Ÿ‡บ๐Ÿ‡ธ", "Spanish ๐Ÿ‡ช๐Ÿ‡ธ", "French ๐Ÿ‡ซ๐Ÿ‡ท", "German ๐Ÿ‡ฉ๐Ÿ‡ช", "Italian ๐Ÿ‡ฎ๐Ÿ‡น", "Portuguese ๐Ÿ‡ต๐Ÿ‡น", "Japanese ๐Ÿ‡ฏ๐Ÿ‡ต", "Korean ๐Ÿ‡ฐ๐Ÿ‡ท", "Chinese ๐Ÿ‡จ๐Ÿ‡ณ", "Arabic ๐Ÿ‡ธ๐Ÿ‡ฆ", "Russian ๐Ÿ‡ท๐Ÿ‡บ", "Hindi ๐Ÿ‡ฎ๐Ÿ‡ณ", "Turkish ๐Ÿ‡น๐Ÿ‡ท", "Polish ๐Ÿ‡ต๐Ÿ‡ฑ", "Dutch ๐Ÿ‡ณ๐Ÿ‡ฑ", "Swedish ๐Ÿ‡ธ๐Ÿ‡ช", "Danish ๐Ÿ‡ฉ๐Ÿ‡ฐ", "Norwegian ๐Ÿ‡ณ๐Ÿ‡ด", "Finnish ๐Ÿ‡ซ๐Ÿ‡ฎ", "Greek ๐Ÿ‡ฌ๐Ÿ‡ท", "Hebrew ๐Ÿ‡ฎ๐Ÿ‡ฑ", "Thai ๐Ÿ‡น๐Ÿ‡ญ", "Vietnamese ๐Ÿ‡ป๐Ÿ‡ณ", "Indonesian ๐Ÿ‡ฎ๐Ÿ‡ฉ", "Malay ๐Ÿ‡ฒ๐Ÿ‡พ", "Filipino ๐Ÿ‡ต๐Ÿ‡ญ", "Ukrainian ๐Ÿ‡บ๐Ÿ‡ฆ", "Czech ๐Ÿ‡จ๐Ÿ‡ฟ", "Slovak ๐Ÿ‡ธ๐Ÿ‡ฐ", "Hungarian ๐Ÿ‡ญ๐Ÿ‡บ", "Romanian ๐Ÿ‡ท๐Ÿ‡ด", "Bulgarian ๐Ÿ‡ง๐Ÿ‡ฌ", "Croatian ๐Ÿ‡ญ๐Ÿ‡ท", "Serbian ๐Ÿ‡ท๐Ÿ‡ธ", "Slovenian ๐Ÿ‡ธ๐Ÿ‡ฎ", "Estonian ๐Ÿ‡ช๐Ÿ‡ช", "Latvian ๐Ÿ‡ฑ๐Ÿ‡ป", "Lithuanian ๐Ÿ‡ฑ๐Ÿ‡น", "Maltese ๐Ÿ‡ฒ๐Ÿ‡น", "Irish ๐Ÿ‡ฎ๐Ÿ‡ช", "Welsh ๐Ÿด", "Icelandic ๐Ÿ‡ฎ๐Ÿ‡ธ", "Faroese ๐Ÿ‡ซ๐Ÿ‡ด", "Luxembourgish ๐Ÿ‡ฑ๐Ÿ‡บ", "Romansh ๐Ÿ‡จ๐Ÿ‡ญ", "Basque ๐Ÿด", "Catalan ๐Ÿด", "Galician ๐Ÿด", "Occitan ๐Ÿ‡ซ๐Ÿ‡ท", "Breton ๐Ÿ‡ซ๐Ÿ‡ท", "Cornish ๐Ÿด", "Scottish Gaelic ๐Ÿด", "Manx ๐Ÿ‡ฎ๐Ÿ‡ฒ", "Norwegian Nynorsk ๐Ÿ‡ณ๐Ÿ‡ด", "Northern Sami ๐Ÿ‡ณ๐Ÿ‡ด", "Belarusian ๐Ÿ‡ง๐Ÿ‡พ", "Macedonian ๐Ÿ‡ฒ๐Ÿ‡ฐ", "Albanian ๐Ÿ‡ฆ๐Ÿ‡ฑ", "Bosnian ๐Ÿ‡ง๐Ÿ‡ฆ", "Montenegrin ๐Ÿ‡ฒ๐Ÿ‡ช", "Kosovo ๐Ÿ‡ฝ๐Ÿ‡ฐ", "San Marino ๐Ÿ‡ธ๐Ÿ‡ฒ", "Andorran ๐Ÿ‡ฆ๐Ÿ‡ฉ", "Liechtenstein ๐Ÿ‡ฑ๐Ÿ‡ฎ", "Monaco ๐Ÿ‡ฒ๐Ÿ‡จ", "Vatican ๐Ÿ‡ป๐Ÿ‡ฆ" ] } }, "publisherPlatforms": { "title": "๐Ÿ“ฑ Publisher Platforms", "type": "array", "description": "**Select which platforms to search for ads** ๐ŸŽฏ\n\n**Available Platforms:**\n- **Facebook** - Main Facebook feed ads\n- **Instagram** - Instagram feed and story ads\n- **Audience Network** - Third-party apps and websites\n- **Messenger** - Facebook Messenger ads\n- **WhatsApp** - WhatsApp Business ads\n- **Threads** - Threads social platform ads\n\n**๐Ÿ’ก Tips:**\n- Leave empty to search all platforms\n- Select multiple platforms for broader coverage\n- Instagram and Facebook are the most common", "items": { "type": "string", "enum": [ "FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER", "WHATSAPP", "THREADS" ], "enumTitles": [ "๐Ÿ“˜ Facebook", "๐Ÿ“ท Instagram", "๐ŸŒ Audience Network", "๐Ÿ’ฌ Messenger", "๐Ÿ“ž WhatsApp", "๐Ÿงต Threads" ] } }, "activeStatus": { "title": "๐Ÿ“Š Ad Status Filter", "enum": [ "ALL", "ACTIVE", "INACTIVE" ], "type": "string", "description": "**Filter by ad activity status** ๐Ÿ”„\n\n- **All**: Both active and inactive ads (recommended)\n- **Active**: Only currently running ads\n- **Inactive**: Only stopped/ended ads\n\n**๐Ÿ’ก 'All' gives the most comprehensive data**", "default": "ALL" }, "adType": { "title": "๐Ÿ“‚ Ad Category Filter", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "type": "string", "description": "**Filter by Facebook ad category** ๐ŸŽฏ\n\n- **All ads**: Every type of advertisement (recommended)\n- **Politics**: Political and issue-based ads\n- **Housing**: Real estate and housing ads\n- **Employment**: Job and employment ads\n- **Financial**: Credit and financial service ads\n\n**๐Ÿ’ก Different categories may have different data availability**", "default": "ALL" }, "mediaType": { "title": "๐ŸŽจ Media Type Filter", "enum": [ "ALL", "IMAGE", "MEME", "IMAGE_AND_MEME", "VIDEO", "NONE" ], "type": "string", "description": "**Filter by ad media content** ๐Ÿ“ฑ\n\n- **All**: Every ad type (recommended)\n- **Video**: Only video ads\n- **Image**: Only image ads\n- **Meme**: Images with text, e.g., 'marketing'\n- **Image & Meme**: Both image types\n- **None**: Text-only ads (no image or video)\n\n**๐Ÿ’ก Video ads often have higher engagement data**", "default": "ALL" }, "startDate": { "title": "๐Ÿ“… From Date", "type": "string", "description": "**Earliest date to search for ads** ๐Ÿ“†\n\nSelect the earliest publication date for ads in your search results." }, "endDate": { "title": "๐Ÿ“… To Date", "type": "string", "description": "**Latest date to search for ads** ๐Ÿ“†\n\nSelect the latest publication date. Leave empty to include all ads up to today." } } }, "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 } } } } } } } } } }