{ "openapi": "3.0.1", "info": { "title": "Meta Ads (Facebook & Instagram) Scraper", "description": "Scrape ads from the Meta Ad Library by URL, keyword, page or ad ID. Filter by country, language, platform, media type, dates and category. Optional add-ons: EU transparency demographics and media downloads.", "version": "0.0", "x-build-id": "iMRGf949HI0ztdW3y" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/lurkapi~meta-ads-facebook-instagram-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-lurkapi-meta-ads-facebook-instagram-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/lurkapi~meta-ads-facebook-instagram-scraper/runs": { "post": { "operationId": "runs-sync-lurkapi-meta-ads-facebook-instagram-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/lurkapi~meta-ads-facebook-instagram-scraper/run-sync": { "post": { "operationId": "run-sync-lurkapi-meta-ads-facebook-instagram-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": "Ads Library URLs", "type": "array", "description": "Paste one or more URLs from facebook.com/ads/library. Any share-link or search URL works.", "items": { "type": "string" } }, "searchQuery": { "title": "Search keywords", "type": "array", "description": "One keyword per line (e.g. 'Nike running shoes', 'Adidas'). Each keyword is scraped separately; results are merged.", "items": { "type": "string" } }, "adIds": { "title": "Ad archive IDs", "type": "array", "description": "List of numeric Ad archive IDs (e.g. 1234567890123). One ID returns exactly one row — the requested ad.", "items": { "type": "string" } }, "pageIds": { "title": "Page IDs or @handles", "type": "array", "description": "List of Facebook Page IDs (numeric) or @handles (e.g. 'nike', 'coca-cola'). We scrape every ad each page has run.", "items": { "type": "string" } }, "country": { "title": "Country", "type": "array", "description": "Pick one or more countries. Defaults to Worldwide.", "items": { "type": "string", "enum": [ "ALL", "AR", "AU", "AT", "BE", "BR", "CA", "CL", "CN", "CO", "CZ", "DK", "EG", "FI", "FR", "DE", "GR", "HK", "HU", "IN", "ID", "IE", "IL", "IT", "JP", "MY", "MX", "NL", "NZ", "NG", "NO", "PE", "PH", "PL", "PT", "RO", "RU", "SA", "SG", "ZA", "KR", "ES", "SE", "CH", "TW", "TH", "TR", "UA", "AE", "GB", "US", "VN" ], "enumTitles": [ "🌍 Worldwide", "Argentina", "Australia", "Austria", "Belgium", "Brazil", "Canada", "Chile", "China", "Colombia", "Czech Republic", "Denmark", "Egypt", "Finland", "France", "Germany", "Greece", "Hong Kong", "Hungary", "India", "Indonesia", "Ireland", "Israel", "Italy", "Japan", "Malaysia", "Mexico", "Netherlands", "New Zealand", "Nigeria", "Norway", "Peru", "Philippines", "Poland", "Portugal", "Romania", "Russia", "Saudi Arabia", "Singapore", "South Africa", "South Korea", "Spain", "Sweden", "Switzerland", "Taiwan", "Thailand", "Turkey", "Ukraine", "United Arab Emirates", "United Kingdom", "United States", "Vietnam" ] }, "default": [ "ALL" ] }, "contentLanguages": { "title": "Content languages", "type": "array", "description": "ISO 639-1 language codes (e.g. en, es, fr).", "items": { "type": "string" }, "default": [] }, "publisherPlatforms": { "title": "Publisher platforms", "type": "array", "description": "Which Meta surfaces the ad ran on.", "items": { "type": "string", "enum": [ "facebook", "instagram", "audience_network", "messenger" ], "enumTitles": [ "Facebook", "Instagram", "Audience Network", "Messenger" ] }, "default": [] }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "image_and_meme", "video", "meme", "none" ], "type": "string", "description": "Filter by ad creative type.", "default": "all" }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Whether the ad is currently running.", "default": "active" }, "adCategory": { "title": "Ad category", "enum": [ "all", "housing_and_real_estate_ads", "employment_ads", "credit_ads", "political_and_issue_ads" ], "type": "string", "description": "Meta's special categories. 'All' includes everything; the others restrict to that special category (audience demographics are exposed by Meta only for these).", "default": "all" }, "dateFrom": { "title": "Start date (from)", "type": "string", "description": "Only ads whose first impression is on or after this date. YYYY-MM-DD. Leave empty for no lower bound." }, "dateTo": { "title": "Start date (to)", "type": "string", "description": "Only ads whose first impression is on or before this date. YYYY-MM-DD. Set both date fields to scan further back than Meta's default 30-day window." }, "sortBy": { "title": "Sort", "enum": [ "impressions_high_to_low", "most_recent" ], "type": "string", "description": "'Impressions: high to low' is the most reliable default. 'Most recent' is supported for time-sensitive monitoring.", "default": "impressions_high_to_low" }, "maxItems": { "title": "Maximum number of ads", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Hard cap on ads scraped across all inputs. Use this to control cost.", "default": 100 }, "includeTransparency": { "title": "📊 EU transparency demographics", "type": "boolean", "description": "Adds age, gender, region breakdown and total reach where Meta exposes them (special-category ads, EU runs). Billed per row where data is returned. See the Pricing tab for rates.", "default": false }, "saveImages": { "title": "🖼️ Save ad images to storage", "type": "boolean", "description": "Downloads every ad image into the run's key-value store. Billed per saved image.", "default": false }, "saveVideosSd": { "title": "🎬 Save SD videos to storage", "type": "boolean", "description": "Downloads SD-quality video files. Billed per saved SD video.", "default": false }, "saveVideosHd": { "title": "🎥 Save HD videos to storage", "type": "boolean", "description": "Downloads HD-quality video files when Meta exposes them. Billed per saved HD video.", "default": false }, "outputAdText": { "title": "Ad text / body copy", "type": "boolean", "description": "Include the ad's body text in each row.", "default": true }, "outputCta": { "title": "Call to action (text, URL, headline, description)", "type": "boolean", "description": "Include CTA button text, link, domain, headline and sub-headline.", "default": true }, "outputPlatforms": { "title": "Publisher platforms", "type": "boolean", "description": "Include the list of Meta surfaces (Facebook, Instagram, Audience Network, Messenger) the ad ran on.", "default": true }, "outputMediaUrls": { "title": "Image / video URLs", "type": "boolean", "description": "Include preview image and video URLs found in the ad creative.", "default": true }, "outputDates": { "title": "Start, end and creation dates", "type": "boolean", "description": "Include the ad's first impression date, end date and creation timestamp.", "default": true }, "outputPageInfo": { "title": "Advertiser page (name, URL, category, likes, verified)", "type": "boolean", "description": "Include the advertiser's Facebook page metadata.", "default": true }, "outputPageInstagram": { "title": "Instagram account info", "type": "boolean", "description": "Include the advertiser's linked Instagram handle and follower count when exposed.", "default": true }, "outputLanguages": { "title": "Detected ad languages", "type": "boolean", "description": "Include the languages Meta detected in the ad creative.", "default": true }, "outputSpendImpressions": { "title": "Spend & impressions (special-category ads only)", "type": "boolean", "description": "Include spend and impression ranges. Meta only exposes these for political, housing, employment and financial ads.", "default": true }, "outputPolitical": { "title": "Political ad metadata (sponsors, payers, audience)", "type": "boolean", "description": "Include political/issue-ad specific fields when present.", "default": true }, "outputSnapshotUrl": { "title": "Ad snapshot URL (Meta's iframe)", "type": "boolean", "description": "Include the URL of the Ads Library snapshot iframe so you can open any ad in your browser.", "default": true } } }, "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 } } } } } } } } } }