{ "openapi": "3.0.1", "info": { "title": "πŸ“’ Facebook Ads Library Scraper Plus", "description": "The Facebook Ads Library Scraper extracts ad data from Facebook’s Ad Library, including advertiser details, ad text, impressions, and targeting info. Ideal for ad research, marketing insights, and competitor analysis, it delivers clean, structured data for analysis or integration via API.", "version": "0.1", "x-build-id": "8OZrIwHeUtpnV5EeZ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scraper-engine~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scraper-engine-facebook-ads-library-scraper", "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/scraper-engine~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-scraper-engine-facebook-ads-library-scraper", "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/scraper-engine~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-scraper-engine-facebook-ads-library-scraper", "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": "πŸ“Œ Pages or Ad Library links", "type": "array", "description": "πŸ”— One entry per line. Plain URLs, or objects with a `url` field (optional `label`, `limit`, `period`). Example: https://www.facebook.com/SHEINOFFICIAL", "items": { "type": "string" } }, "searchTerms": { "title": "πŸ” Keyword search terms", "type": "array", "description": "πŸ”Ž Search the Ad Library by keyword β€” no URL needed. Each term becomes a search across the countries below. Example: [\"vpn\", \"protein powder\"].", "items": { "type": "string" } }, "searchCountries": { "title": "🌍 Search countries", "type": "array", "description": "πŸ—ΊοΈ ISO country codes for keyword search (EU codes like DE/FR/IE populate the reach block). Use ALL for worldwide. Example: [\"DE\", \"FR\"]. Defaults to the country below.", "items": { "type": "string" } }, "searchMode": { "title": "πŸ”€ Keyword match mode", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "🧩 How keyword search matches ad text.", "default": "keyword_unordered" }, "resultsLimit": { "title": "πŸ”’ Maximum ads", "minimum": 1, "maximum": 50000, "type": "integer", "description": "πŸ“ˆ Upper bound on ad rows returned across all sources. Lower = faster; higher = broader coverage. Default 10.", "default": 10 }, "isDetailsPerAd": { "title": "✨ Enrich each ad (EU reach + advertiser)", "type": "boolean", "description": "πŸ” Runs a details lookup per ad to add the EU DSA reach block, advertiser info, and richer creative. Turn off for a faster listing-only export (no EU reach). Default on.", "default": true }, "onlyTotal": { "title": "πŸ”’ Only return total counts", "type": "boolean", "description": "πŸ“‰ One summary row per source with a total ad count β€” handy for quick audits.", "default": false }, "includeAboutPage": { "title": "ℹ️ Include page \"about\" snippet", "type": "boolean", "description": "πŸ“„ For Facebook page sources, attach the public title/description text when available.", "default": false }, "countryCode": { "title": "🌍 Default country (page sources)", "enum": [ "ALL", "AR", "AU", "AT", "BE", "BR", "CA", "CL", "CO", "CZ", "DK", "FI", "FR", "DE", "GR", "HU", "IN", "ID", "IE", "IL", "IT", "JP", "MX", "NL", "NZ", "NO", "PL", "PT", "RO", "SA", "SG", "ZA", "KR", "ES", "SE", "CH", "TR", "AE", "GB", "US", "UA" ], "type": "string", "description": "πŸ“ Region for Facebook page sources when the URL does not pin one. Ad Library links carry their own country.", "default": "ALL" }, "activeStatus": { "title": "⚑ Ad activity", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "πŸŽ›οΈ Filter by ad status for page sources or when the Ad Library link leaves it unspecified.", "default": "all" }, "adType": { "title": "πŸ—‚οΈ Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads" ], "type": "string", "description": "πŸ“ Which Ad Library category to query. \"All ads\" covers commercial ads; the others cover regulated categories.", "default": "all" }, "mediaType": { "title": "πŸ“Ί Media type", "enum": [ "all", "image", "video" ], "type": "string", "description": "πŸ–ΌοΈ Restrict to a creative format (queried and post-filtered).", "default": "all" }, "publisherPlatforms": { "title": "πŸ“± Publisher platforms", "type": "array", "description": "πŸ”Ž Keep only ads shown on the selected Meta platforms. Leave empty for all. Example: [\"FACEBOOK\", \"INSTAGRAM\"].", "items": { "type": "string", "enum": [ "FACEBOOK", "INSTAGRAM", "MESSENGER", "AUDIENCE_NETWORK", "THREADS", "WHATSAPP" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads", "WhatsApp" ] }, "default": [] }, "keywords": { "title": "πŸ”Ž Must contain keywords", "type": "array", "description": "βœ… Keep only ads whose copy/title/caption contains at least one of these words. Example: [\"sale\", \"free shipping\"].", "items": { "type": "string" } }, "excludeKeywords": { "title": "🚫 Exclude keywords", "type": "array", "description": "❌ Drop ads whose copy contains any of these words. Example: [\"casino\", \"crypto\"].", "items": { "type": "string" } }, "minPageLikes": { "title": "πŸ‘ Minimum page likes", "minimum": 0, "type": "integer", "description": "πŸ“Š Keep only ads whose advertiser page has at least this many likes. 0 = no minimum.", "default": 0 }, "minEuReach": { "title": "πŸ‡ͺπŸ‡Ί Minimum EU reach", "minimum": 0, "type": "integer", "description": "πŸ“ˆ Keep only ads whose EU total reach is at least this value (drops ads without reported reach). 0 = no minimum.", "default": 0 }, "onlyAdsNewerThan": { "title": "πŸ“… Only ads started after", "type": "string", "description": "⏳ Keep ads whose start date is on/after this date. Absolute (2025-01-01) or relative (30 days)." }, "onlyAdsOlderThan": { "title": "πŸ“… Only ads started before", "type": "string", "description": "⏳ Keep ads whose start date is on/before this date. Absolute or relative." }, "period": { "title": "πŸ“† Default time range (page sources)", "pattern": "^$|^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$|^(\\d+)\\s*(day|week|month|year)s?$", "type": "string", "description": "⏳ Optional window passed to the Ad Library for page sources. Leave empty to use the library default.", "default": "" }, "filterDuplicatePageIds": { "title": "🧹 One ad per advertiser page", "type": "boolean", "description": "πŸ” Keep only the first ad from each advertiser page (in addition to the always-on dedup by ad ID).", "default": false }, "aiEnhancement": { "title": "πŸ€– Enable AI enrichment", "type": "boolean", "description": "🧠 Analyze each ad's copy with an LLM. Needs an API key below (or the matching provider env var).", "default": false }, "aiModel": { "title": "πŸ€– AI Model / Provider", "enum": [ "claude-haiku-4-5", "claude-sonnet-5", "claude-opus-4-8", "gpt-4o-mini", "gpt-4o", "gpt-4.1-mini", "o3-mini", "gemini-2.0-flash-lite", "gemini-2.0-flash", "gemini-2.5-flash", "grok-3-mini", "deepseek-chat", "sonar", "mistral-small-latest" ], "type": "string", "description": "Provider auto-detected from the name: claude-*=Anthropic, gpt-*/o1/o3=OpenAI, gemini-*=Google, grok-*=xAI, deepseek-*=DeepSeek, sonar*=Perplexity, mistral-*=Mistral. Cheaper mini/flash/haiku models are recommended.", "default": "claude-haiku-4-5" }, "aiApiKey": { "title": "πŸ”‘ AI API key", "type": "string", "description": "Secret API key for the chosen provider. If empty, the matching env var is used (ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / XAI_API_KEY / DEEPSEEK_API_KEY / PERPLEXITY_API_KEY / MISTRAL_API_KEY)." }, "proxyConfiguration": { "title": "πŸ›‘οΈ Proxy (optional)", "type": "object", "description": "🏠 Leave off for a standard run. If you enable Apify Proxy, only residential traffic is used. Requires proxy access on your plan." } } }, "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 } } } } } } } } } }