{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper — EU Reach, Agency & Contacts", "description": "Ads from the Meta Ad Library (Facebook, Instagram, Messenger, Threads) by keyword, advertiser or link: copy, creatives, dates, platforms, landing page. EU reach, age/gender/country split, targeting and payer as columns; agency detection; optional advertiser e-mail/phone and image OCR.", "version": "0.1", "x-build-id": "XbuvZXTNFRWu5cnyX" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/foxlabs~meta-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-foxlabs-meta-ad-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/foxlabs~meta-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-foxlabs-meta-ad-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/foxlabs~meta-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-foxlabs-meta-ad-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": "Search terms", "type": "array", "description": "One per line: words to search in the Ad Library, as you would type them on facebook.com/ads/library (\"running shoes\", \"dentist\", a brand name). Meta matches the words in the ads. Each search returns up to \"Max ads per search\".", "items": { "type": "string" } }, "advertisers": { "title": "Advertisers (pages)", "type": "array", "description": "One per line: an advertiser's Facebook page ID (15087023444), page link (https://www.facebook.com/nike) or name (\"Nike\"). Returns the ads that page runs. A name or page link is matched against the advertisers of the ads that mention it; when no page matches you get a free row with the reason, and the page ID always works.", "items": { "type": "string" } }, "adLibraryUrls": { "title": "Ad Library links", "type": "array", "description": "One per line: links copied from facebook.com/ads/library: a search with its filters, an advertiser's page of ads (view_all_page_id) or a single ad (?id=). Filters inside a link win over the filters below.", "items": { "type": "string" } }, "searchType": { "title": "Match", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "How the search terms are matched.", "default": "keyword_unordered" }, "country": { "title": "Country", "enum": [ "ALL", "AL", "DZ", "AR", "AM", "AU", "AT", "AZ", "BH", "BD", "BY", "BE", "BO", "BA", "BR", "BG", "KH", "CM", "CA", "CL", "CO", "CR", "HR", "CY", "CZ", "DK", "DO", "EC", "EG", "SV", "EE", "ET", "FI", "FR", "GE", "DE", "GH", "GR", "GT", "HN", "HK", "HU", "IS", "IN", "ID", "IQ", "IE", "IL", "IT", "CI", "JM", "JP", "JO", "KZ", "KE", "XK", "KW", "LV", "LB", "LI", "LT", "LU", "MY", "MT", "MX", "MD", "MN", "ME", "MA", "NP", "NL", "NZ", "NI", "NG", "MK", "NO", "OM", "PK", "PA", "PY", "PE", "PH", "PL", "PT", "PR", "QA", "RO", "SA", "SN", "RS", "SG", "SK", "SI", "ZA", "KR", "ES", "LK", "SE", "CH", "TW", "TZ", "TH", "TN", "TR", "UG", "UA", "AE", "GB", "US", "UY", "UZ", "VE", "VN" ], "type": "string", "description": "Ads shown in this country. In EU countries Meta publishes the reach, age/gender split, targeting and payer of nearly every ad (998 of 1,000 German ads; see \"EU transparency\"); elsewhere only for political and issue ads and for ads also shown in the EU. \"All countries\" searches everywhere.", "default": "ALL" }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Running now, stopped, or both. Stopped ads are listed in the US too (a \"nike\" search listed more than 50,000).", "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": "The Ad Library's ad categories. Political and issue ads carry spend, impressions and the audience split.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ], "type": "string", "description": "Creative type of the ads.", "default": "all" }, "platforms": { "title": "Platforms", "type": "array", "description": "Only ads that run on these platforms. Empty = all platforms.", "items": { "type": "string", "enum": [ "facebook", "instagram", "audience_network", "messenger", "threads" ], "enumTitles": [ "Facebook", "Instagram", "Audience Network", "Messenger", "Threads" ] } }, "languages": { "title": "Ad languages", "type": "array", "description": "Two-letter language codes of the ads, such as en, de, fr, tr. Empty = all languages.", "items": { "type": "string" } }, "datePreset": { "title": "Shown in period", "enum": [ "any", "last_7_days", "last_30_days", "last_90_days", "custom" ], "type": "string", "description": "Only ads Meta showed in this period (the Ad Library's \"impressions by date\" filter). \"Custom\" uses the two dates below.", "default": "any" }, "dateFrom": { "title": "From (custom period)", "type": "string", "description": "YYYY-MM-DD. Used only when \"Shown in period\" is Custom." }, "dateTo": { "title": "To (custom period)", "type": "string", "description": "YYYY-MM-DD. Used only when \"Shown in period\" is Custom." }, "sortBy": { "title": "Order", "enum": [ "relevance", "impressions", "newest" ], "type": "string", "description": "Order of the results, as on the website. \"Most impressions\" puts the ads with the most impressions first. \"Newest\" is Meta's newest-first order, which is not a strict date order.", "default": "relevance" }, "maxAdsPerQuery": { "title": "Max ads per search", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop each search, advertiser or link after this many ads (up to 10000). The form starts at 10 for a quick first run; an API call without this field gets 100. You pay per ad delivered.", "default": 100 }, "includeEuTransparency": { "title": "EU transparency and political audience", "type": "boolean", "description": "For ads shown in the EU: total EU reach, reach by country, age and gender, targeted locations, ages and gender, and the payer and beneficiary (with \"paidByThirdParty\" when an agency or other company paid). For political and issue ads: the audience split. One extra request per such ad; included in the ad price.", "default": true }, "includeAdvertiserInfo": { "title": "Advertiser info (About tab)", "type": "boolean", "description": "Per advertiser, from the page's About tab: the legal owner Meta confirmed and its country (large brands usually have one; none of 65 dental practices did), and the Instagram account and page verification for ads outside the EU (EU ads already carry them). With \"Advertiser contacts\" on, the advertiser rows also get the page admins' countries, the page's creation date and name changes. One extra request per advertiser: a broad search took about twice as long with it. Included in the ad price.", "default": false }, "includeAdvertiserContacts": { "title": "Advertiser contacts (leads)", "type": "boolean", "description": "Adds one row per advertiser with its website (from its ads' landing pages) and the e-mails and phone numbers the website publishes (home page, then its legal notice / Impressum or contact page). Charged per advertiser only when at least one e-mail or phone is found.", "default": false }, "ocrImageAds": { "title": "Text inside images (OCR)", "type": "boolean", "description": "Reads the text written in image ads (headlines, prices, offers in the picture) into \"imageText\". Slower: a few seconds per image. Charged per ad only when text is found.", "default": false }, "onlyNewAds": { "title": "Only new ads since the last run", "type": "boolean", "description": "For scheduled runs: remembers the ads each search delivered (in a key-value store named by \"Monitor name\" in your account) and delivers only ads that search has not delivered before. The memory is per search: the same term, advertiser or link with the same filters; a changed filter starts a new list. Known ads are skipped and not charged, and the search reads on until it has \"Max ads per search\" new ads (at most about Max/10 + 30 result pages).", "default": false }, "monitorName": { "title": "Monitor name", "type": "string", "description": "Name of the key-value store that keeps the delivered ad IDs (letters, digits, dashes). Use one name per monitored set of searches. Empty = meta-ad-library-monitor." } } }, "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 } } } } } } } } } }