{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper", "description": "Facebook Ads Library scraper: export the ads of any Facebook page, keyword or Meta Ad Library URL (filters kept) without a Facebook account. Ad copy, creatives, CTA, links, platforms, dates, and optionally the products behind each ad. Exact limit, pay per ad.", "version": "1.0", "x-build-id": "Fr0oeQ3STbTDzXgnz" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/badr_xba~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-badr_xba-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/badr_xba~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-badr_xba-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/badr_xba~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-badr_xba-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": "🔗 Meta Ad Library URL or Facebook Page URL", "type": "array", "description": "One per line. Accepted: a Facebook Page URL (https://www.facebook.com/SHEINOFFICIAL, m.facebook.com/nike, facebook.com/profile.php?id=100064…), an advertiser or search URL from the Meta Ad Library (set your keyword, country, platforms, language and media filters on facebook.com/ads/library, then copy the URL), or a single ad URL (https://www.facebook.com/ads/library/?id=…). Duplicates and extra spaces are removed automatically; a URL that is not Facebook is skipped and listed in FAILED_INPUTS (not billed).", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "searchQueries": { "title": "🔎 Or search keywords / page names", "type": "array", "description": "Optional. Keywords searched in the text of the ads, in the country below (ALL = every country), e.g. running shoes or black friday. Start with @ to get a page's ads instead: @nike. Each keyword uses the same results limit.", "items": { "type": "string" } }, "resultsLimit": { "title": "💯 Results limit per URL", "minimum": 1, "type": "integer", "description": "Ads per URL or keyword. The limit is exact: you never get (or pay for) more. Leave empty to get every ad the library shows (a big brand can have thousands)." }, "country": { "title": "🌍 Country (for page URLs)", "enum": [ "ALL", "US", "GB", "CA", "AU", "FR", "DE", "ES", "IT", "NL", "BE", "CH", "AT", "PT", "IE", "SE", "NO", "DK", "FI", "PL", "CZ", "RO", "GR", "TR", "MA", "DZ", "TN", "EG", "SA", "AE", "QA", "KW", "IN", "PK", "ID", "MY", "SG", "PH", "TH", "VN", "JP", "KR", "BR", "MX", "AR", "CO", "CL", "PE", "ZA", "NG", "KE", "NZ", "IL", "UA" ], "type": "string", "description": "Where the ads ran, for page URLs, page names and keywords. ALL = every country. Ad Library URLs keep their own country.", "default": "ALL" }, "onlyTotal": { "title": "Get only the total ad count per page", "type": "boolean", "description": "One row per URL with the total number of ads, instead of the ads themselves.", "default": false }, "includeAboutPage": { "title": "Include page \"About\" information", "type": "boolean", "description": "Adds pageInfo: page name, URL, profile photo, description and the related pages of the advertiser in other countries.", "default": false }, "isDetailsPerAd": { "title": "Include extra ad details (spend, reach, Instagram data)", "type": "boolean", "description": "Opens each ad's detail and adds ad_details: Instagram username and followers, page likes, category and verification, page spend and political status, and for EU ads the audience, reach by country, age and gender, payer and beneficiary. Slower (one request per ad).", "default": false }, "activeStatus": { "title": "🖱️ Active status (if not in the Ad Library URL)", "enum": [ "", "active", "inactive" ], "type": "string", "description": "Ads still running, stopped ones, or both. A value already in the URL wins.", "default": "" }, "sorting": { "title": "🗂️ Sorting (if not in the Ad Library URL)", "enum": [ "", "total_impressions", "relevancy_monthly_grouped" ], "type": "string", "description": "Order of the ads. A value already in the URL wins.", "default": "" }, "onlyAdsNewerThan": { "title": "Scrape ads newer than", "type": "string", "description": "Only ads active on or after this date: 2024-01-01 or \"2 months\"." }, "onlyAdsOlderThan": { "title": "Scrape ads older than", "type": "string", "description": "Only ads active on or before this date: 2024-12-31 or \"1 year\"." }, "minDaysRunning": { "title": "Minimum days running", "minimum": 1, "type": "integer", "description": "Optional. Keep only ads that ran at least this many days (first and last day included; an active ad counts until today). Long-running ads are usually the ones that work. Shorter ads are skipped and not billed; the results limit counts only the ads kept. Leave empty to keep every ad." }, "enrichWithEcommerceData": { "title": "$ Enrich with e-commerce data", "type": "boolean", "description": "Follows each ad's links and adds the product behind them (name, price, currency, brand, image, description, rating) as ecommerceData. Billed per product found; links that are not product pages (sign-up, app, catalog templates) are free.", "default": false }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Leave as it is (no proxy): the Actor reads the Ad Library directly and switches to Apify addresses when Facebook refuses or slows it down.", "default": { "useApifyProxy": false } }, "runTag": { "title": "Run tag", "type": "string", "description": "Optional label (e.g. competitor-watch-week-45) copied to every row as runTag, to tell runs apart when you merge datasets. Leave empty for no tag." } } }, "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 } } } } } } } } } }