{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper | EU Reach, Targeting & Alerts", "description": "Scrape the Facebook / Meta Ads Library by keyword, advertiser page or link in 100+ countries. Get ad copy, creatives, platforms, days running, EU & UK reach by country, age and gender, targeting, payer, Instagram followers and political spend. New-ad alerts. No login.", "version": "0.1", "x-build-id": "VSw8Xfzf5OyRF3rsk" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/corvuslab~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-corvuslab-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/corvuslab~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-corvuslab-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/corvuslab~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-corvuslab-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": { "searchQueries": { "title": "๐Ÿ”‘ Keywords", "type": "array", "description": "Words to find in ads, for example a brand, product or topic. Each keyword is its own search; ads found by several keywords are returned once.", "items": { "type": "string" } }, "pageUrls": { "title": "๐Ÿข Advertiser pages", "type": "array", "description": "Facebook page links (https://www.facebook.com/nike) or numeric page IDs. Returns the ads that page runs in the selected countries.", "items": { "type": "string" } }, "startUrls": { "title": "๐Ÿ”— Ad Library links", "type": "array", "description": "Paste results links straight from facebook.com/ads/library, with the filters you set there. A single-ad link (โ€ฆ/ads/library/?id=โ€ฆ) returns that one ad.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxResults": { "title": "๐Ÿ”ข Max ads per search", "minimum": 0, "type": "integer", "description": "How many ads to return for each keyword, advertiser or link. 0 = everything the library lists.", "default": 50 }, "countries": { "title": "๐ŸŒ Countries", "type": "array", "description": "Where the ads were shown. Pick several to run each search once per country (each ad is still returned once).", "items": { "type": "string", "enum": [ "ALL", "US", "GB", "CA", "AU", "NZ", "IE", "DE", "FR", "ES", "IT", "NL", "BE", "LU", "AT", "CH", "SE", "DK", "NO", "FI", "IS", "PL", "CZ", "SK", "HU", "RO", "BG", "GR", "PT", "HR", "SI", "RS", "BA", "EE", "LV", "LT", "CY", "MT", "UA", "TR", "IL", "AE", "SA", "QA", "KW", "BH", "OM", "JO", "LB", "EG", "MA", "DZ", "TN", "NG", "KE", "GH", "ZA", "ET", "TZ", "UG", "CI", "SN", "CM", "IN", "PK", "BD", "LK", "NP", "SG", "MY", "ID", "TH", "VN", "PH", "KH", "MM", "JP", "KR", "TW", "HK", "MX", "BR", "AR", "CL", "CO", "PE", "EC", "VE", "UY", "PY", "BO", "GT", "CR", "PA", "DO", "PR", "HN", "SV", "NI", "JM", "TT", "KZ", "UZ", "GE", "AM", "AZ", "MD", "AL", "MK", "ME" ], "enumTitles": [ "All countries", "United States", "United Kingdom", "Canada", "Australia", "New Zealand", "Ireland", "Germany", "France", "Spain", "Italy", "Netherlands", "Belgium", "Luxembourg", "Austria", "Switzerland", "Sweden", "Denmark", "Norway", "Finland", "Iceland", "Poland", "Czechia", "Slovakia", "Hungary", "Romania", "Bulgaria", "Greece", "Portugal", "Croatia", "Slovenia", "Serbia", "Bosnia and Herzegovina", "Estonia", "Latvia", "Lithuania", "Cyprus", "Malta", "Ukraine", "Turkey", "Israel", "United Arab Emirates", "Saudi Arabia", "Qatar", "Kuwait", "Bahrain", "Oman", "Jordan", "Lebanon", "Egypt", "Morocco", "Algeria", "Tunisia", "Nigeria", "Kenya", "Ghana", "South Africa", "Ethiopia", "Tanzania", "Uganda", "Ivory Coast", "Senegal", "Cameroon", "India", "Pakistan", "Bangladesh", "Sri Lanka", "Nepal", "Singapore", "Malaysia", "Indonesia", "Thailand", "Vietnam", "Philippines", "Cambodia", "Myanmar", "Japan", "South Korea", "Taiwan", "Hong Kong", "Mexico", "Brazil", "Argentina", "Chile", "Colombia", "Peru", "Ecuador", "Venezuela", "Uruguay", "Paraguay", "Bolivia", "Guatemala", "Costa Rica", "Panama", "Dominican Republic", "Puerto Rico", "Honduras", "El Salvador", "Nicaragua", "Jamaica", "Trinidad and Tobago", "Kazakhstan", "Uzbekistan", "Georgia", "Armenia", "Azerbaijan", "Moldova", "Albania", "North Macedonia", "Montenegro" ] }, "default": [ "ALL" ] }, "activeStatus": { "title": "๐ŸŸข Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Running ads, stopped ads, or both.", "default": "active" }, "adType": { "title": "๐Ÿท๏ธ Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads", "financial_products_and_services_ads" ], "type": "string", "description": "Special ad categories. Political and issue ads also carry spend ranges and audience shares.", "default": "all" }, "mediaType": { "title": "๐Ÿ–ผ๏ธ Media type", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ], "type": "string", "description": "Only ads with this kind of creative.", "default": "all" }, "publisherPlatforms": { "title": "๐Ÿ“ฑ Platforms", "type": "array", "description": "Only ads shown on these platforms. Leave empty for all.", "items": { "type": "string", "enum": [ "facebook", "instagram", "audience_network", "messenger", "threads", "whatsapp" ], "enumTitles": [ "Facebook", "Instagram", "Audience Network", "Messenger", "Threads", "WhatsApp" ] } }, "searchType": { "title": "๐Ÿ”ค Keyword match", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "How keywords are matched against the ad text.", "default": "keyword_unordered" }, "contentLanguages": { "title": "๐Ÿ—ฃ๏ธ Ad languages", "type": "array", "description": "Two-letter language codes, for example en, de, es. Leave empty for all languages.", "items": { "type": "string" } }, "dateFrom": { "title": "๐Ÿ“… Shown from", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}$|^\\d+\\s*(day|days|week|weeks|month|months|year|years)$", "type": "string", "description": "Ads that were shown on or after this day: 2026-10-01, or a relative '7 days'." }, "dateTo": { "title": "๐Ÿ“… Shown until", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}$|^\\d+\\s*(day|days|week|weeks|month|months|year|years)$", "type": "string", "description": "Ads that were shown on or before this day." }, "onlyAdsNewerThan": { "title": "๐Ÿ†• Only ads launched after", "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}$|^\\d+\\s*(day|days|week|weeks|month|months|year|years)$", "type": "string", "description": "Keep only ads whose start date is on or after this day: 2026-10-01, or '30 days'. Unlike 'Shown from', ads launched earlier are left out even if they are still running." }, "includeDetails": { "title": "๐Ÿ‡ช๐Ÿ‡บ Add transparency details", "type": "boolean", "description": "Adds each ad's EU and UK reach (by country, age and gender), targeted age, gender and locations, the payer and beneficiary, and the advertiser's profile (verification, Instagram followers, about text). Reach and audience exist for ads shown in the EU or UK.", "default": true }, "compact": { "title": "๐Ÿค Compact output", "type": "boolean", "description": "Return only the core fields: advertiser, dates, platforms, ad copy, link, media and EU reach. Handy for AI agents and spreadsheets.", "default": false }, "excludeEmptyFields": { "title": "๐Ÿงน Leave out empty fields", "type": "boolean", "description": "Drop fields that have no value instead of returning them as null.", "default": false }, "incrementalMode": { "title": "โ™ป๏ธ Only new and changed ads", "type": "boolean", "description": "Remember the ads seen on earlier runs of this search and return only NEW ads and ones whose copy or status changed (see changeType).", "default": false }, "stateKey": { "title": "๐Ÿ—๏ธ Monitor name", "type": "string", "description": "Optional name for this monitor's memory. Runs with the same name share it; leave empty to derive it from the search." }, "emitUnchanged": { "title": "Return unchanged ads too", "type": "boolean", "description": "Also return ads that have not changed, marked UNCHANGED (these are charged).", "default": false }, "emitExpired": { "title": "Report stopped ads", "type": "boolean", "description": "Return a short EXPIRED row for each ad from the last run that no longer appears, for example an ad the advertiser switched off. Only on runs that read the whole search; each row counts as a result.", "default": false }, "telegramToken": { "title": "Telegram bot token", "type": "string", "description": "From @BotFather." }, "telegramChatId": { "title": "Telegram chat ID", "type": "string", "description": "The chat or channel to post to." }, "slackWebhookUrl": { "title": "Slack webhook URL", "type": "string", "description": "An incoming-webhook URL." }, "discordWebhookUrl": { "title": "Discord webhook URL", "type": "string", "description": "A channel webhook URL." }, "webhookUrl": { "title": "Webhook URL", "type": "string", "description": "Receives a JSON POST with the new ads." }, "webhookHeaders": { "title": "Webhook headers", "type": "object", "description": "Extra headers for the webhook, for example an Authorization header." }, "notificationLimit": { "title": "Ads per notification", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many ads each message lists.", "default": 5 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Keep the preselected setting: it is what keeps long searches reliable.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "detailConcurrency": { "title": "Parallel detail requests", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many transparency panels to read at once.", "default": 4 }, "maxRequestRetries": { "title": "Max retries", "minimum": 1, "maximum": 8, "type": "integer", "description": "Retries per page before a search is given up.", "default": 3 } } }, "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 } } } } } } } } } }