{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library", "description": "🧲 ONLY 0.5$/1000 Results : Scrape Facebook Ad Library at scale. Extract ads, creatives, videos, CTAs, links & platforms. Enable Ad Details for EU reach, demographics & audience targeting. Multi-URL, auto-pagination, MCP ready", "version": "1.1", "x-build-id": "RFgKZP5pCmpg92W0b" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/data_xplorer~facebook-ads-library/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-data_xplorer-facebook-ads-library", "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/data_xplorer~facebook-ads-library/runs": { "post": { "operationId": "runs-sync-data_xplorer-facebook-ads-library", "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/data_xplorer~facebook-ads-library/run-sync": { "post": { "operationId": "run-sync-data_xplorer-facebook-ads-library", "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": { "urls": { "title": "Ad Library URLs", "type": "array", "description": "List of Facebook Ad Library URLs to scrape. Optional if you use the keyword search below.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "keywords": { "title": "Keywords", "type": "array", "description": "One search per keyword, for example a brand, a product or a topic. Each keyword returns up to the maximum number of ads set below.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "ALL", "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "DY", "BM", "BT", "BO", "BA", "BW", "BR", "VG", "BN", "BG", "BF", "HV", "BI", "KH", "CM", "CA", "CV", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "HR", "CU", "CW", "CY", "CZ", "CI", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "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", "KP", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RO", "RU", "RW", "RE", "WS", "SM", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "KR", "SS", "ES", "LK", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "SD", "SR", "SJ", "SE", "CH", "SY", "ST", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TM", "TC", "TV", "TR", "VI", "UG", "UA", "AE", "GB", "UK", "US", "UY", "UZ", "NH", "VU", "VA", "VE", "VD", "VN", "WF", "EH", "YE", "ZM", "RH", "ZW", "AX" ], "type": "string", "description": "Country where the ads were shown.", "default": "ALL" }, "adCategory": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads" ], "type": "string", "description": "Facebook offers different categories depending on the country. For example, politics is available in the US, the UK or Brazil but not in France, and housing, employment and financial products are not offered in Brazil.", "default": "all" }, "adStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Only running ads, only stopped ads, or both.", "default": "active" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ], "type": "string", "description": "Keep only ads with this kind of creative.", "default": "all" }, "platforms": { "title": "Platforms", "type": "array", "description": "Only ads shown on these platforms. Leave empty for all platforms.", "items": { "type": "string", "enum": [ "facebook", "instagram", "messenger", "whatsapp", "threads", "audience_network" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "WhatsApp", "Threads", "Audience Network" ] } }, "languages": { "title": "Ad language", "type": "array", "description": "Only ads written in these languages. Leave empty for all languages.", "items": { "type": "string", "enum": [ "ar", "bn", "bg", "ca", "zh", "hr", "cs", "da", "nl", "en", "et", "fil", "fi", "fr", "de", "el", "he", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "no", "fa", "pl", "pt", "ro", "ru", "sr", "sk", "sl", "es", "sw", "sv", "ta", "th", "tr", "uk", "ur", "vi" ], "enumTitles": [ "Arabic", "Bangla", "Bulgarian", "Catalan", "Chinese", "Croatian", "Czech", "Danish", "Dutch", "English", "Estonian", "Filipino", "Finnish", "French", "German", "Greek", "Hebrew", "Hindi", "Hungarian", "Indonesian", "Italian", "Japanese", "Korean", "Latvian", "Lithuanian", "Malay", "Norwegian", "Persian", "Polish", "Portuguese", "Romanian", "Russian", "Serbian", "Slovak", "Slovenian", "Spanish", "Swahili", "Swedish", "Tamil", "Thai", "Turkish", "Ukrainian", "Urdu", "Vietnamese" ] } }, "dateFrom": { "title": "Shown from", "type": "string", "description": "Only ads with impressions on or after this date (YYYY-MM-DD). Leave empty for no limit." }, "dateTo": { "title": "Shown until", "type": "string", "description": "Only ads with impressions on or before this date (YYYY-MM-DD). Leave empty for no limit." }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "impressions", "recent" ], "type": "string", "description": "Order in which ads are returned. With a max number of ads, it decides which ads you get.", "default": "relevance" }, "exactPhrase": { "title": "Exact phrase", "type": "boolean", "description": "When enabled, ads must contain the keyword as an exact phrase. Otherwise ads with all the words in any order are returned.", "default": false }, "maxAds": { "title": "Max ads per URL or keyword", "minimum": 0, "type": "integer", "description": "Maximum number of ads to scrape for each URL and each keyword. Set 0 for unlimited.", "default": 100 }, "fetchDetails": { "title": "Fetch Ad Details", "type": "boolean", "description": "Fetch detailed targeting data (audience, reach, demographics) for each ad. Adds extra API calls.", "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }