{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper - Meta & Instagram Ads, No Login", "description": "Scrape Facebook, Instagram & Meta ads from the public Ad Library by keyword, Page or URL. Ad copy, all images & videos, carousel cards, CTA, links, run dates and advertiser data - 50+ fields per ad, no login. $0.005 per run + $0.75 per 1,000 ads. Export JSON, CSV or Excel.", "version": "0.1", "x-build-id": "PetAp3Q3JKO9dHjQ3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapesage~facebook-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapesage-facebook-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/scrapesage~facebook-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-scrapesage-facebook-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/scrapesage~facebook-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-scrapesage-facebook-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": { "searchTerms": { "title": "Search terms (keywords)", "type": "array", "description": "Keywords to search the Ad Library for, e.g. \"nike\", \"electric scooter\". Each term runs as its own search. Leave empty if you only use Page URLs or Ad Library URLs.", "items": { "type": "string" } }, "pageUrls": { "title": "Facebook Page URLs or IDs", "type": "array", "description": "Facebook page URLs (e.g. https://www.facebook.com/nike), page names, or numeric page IDs. Returns the ads run by that advertiser. A page URL or name is matched to its page ID automatically (one small extra request the first time; later runs reuse it), so every result comes from that page.", "items": { "type": "string" } }, "startUrls": { "title": "Ad Library URLs", "type": "array", "description": "Paste full Meta Ad Library URLs (https://www.facebook.com/ads/library/?...). Every filter encoded in the URL is preserved — the best way to target an exact page or a complex filter combination.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "country": { "title": "Country", "enum": [ "ALL", "US", "GB", "CA", "AU", "IE", "DE", "FR", "ES", "IT", "NL", "SE", "PL", "PT", "BR", "MX", "AR", "IN", "ID", "PH", "TH", "VN", "JP", "KR", "TR", "AE", "SA", "ZA", "NG", "EG", "NZ", "BE", "CH", "AT", "DK", "NO", "FI", "GR", "CZ", "RO", "HU" ], "type": "string", "description": "Country whose Ad Library to query. Use ALL to search every country at once. Accepts any ISO-3166 two-letter code via Ad Library URLs.", "default": "US" }, "adActiveStatus": { "title": "Ad status", "enum": [ "ALL", "ACTIVE", "INACTIVE" ], "type": "string", "description": "Return currently-running ads, stopped ads, or both.", "default": "ALL" }, "adType": { "title": "Ad category", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "type": "string", "description": "ALL covers every public ad. The transparency categories surface extra disclosures (audience estimates, sometimes spend) for political/issue, housing, employment, and credit ads.", "default": "ALL" }, "mediaType": { "title": "Media type", "enum": [ "ALL", "IMAGE", "VIDEO", "MEME", "NONE" ], "type": "string", "description": "Restrict results by creative format.", "default": "ALL" }, "publisherPlatforms": { "title": "Platforms", "type": "array", "description": "Only include ads that ran on these Meta surfaces. Leave empty for all.", "items": { "type": "string", "enum": [ "FACEBOOK", "INSTAGRAM", "MESSENGER", "AUDIENCE_NETWORK", "THREADS", "WHATSAPP" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads", "WhatsApp" ] }, "default": [] }, "languages": { "title": "Languages", "type": "array", "description": "Only include ads whose creative is in one of these languages. Leave empty for any.", "items": { "type": "string", "enum": [ "en", "es", "pt", "fr", "de", "it", "nl", "pl", "tr", "ru", "ar", "he", "ja", "ko", "zh", "hi", "id", "th", "vi" ], "enumTitles": [ "English", "Spanish", "Portuguese", "French", "German", "Italian", "Dutch", "Polish", "Turkish", "Russian", "Arabic", "Hebrew", "Japanese", "Korean", "Chinese", "Hindi", "Indonesian", "Thai", "Vietnamese" ] }, "default": [] }, "dateFrom": { "title": "Started on or after", "type": "string", "description": "Only include ads that were still running on or after this date (YYYY-MM-DD) — the same date filter as the Ad Library site, applied to every page of results." }, "dateTo": { "title": "Started on or before", "type": "string", "description": "Only include ads that had started by this date (YYYY-MM-DD). With a start date, this selects the ads that were live at any point in the range — the same date filter as the Ad Library site, applied to every page of results." }, "maxResults": { "title": "Max ads", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Cap on total ads collected across every source. Set to 0 for unlimited (paginates until Meta returns no more). Each ad written is one billable result. In monitoring mode this caps how many ads are SCANNED per run, and there it is limited to 60 — scanning is what a run costs, so an unbounded monitoring scan is not offered.", "default": 100 }, "monitoringMode": { "title": "Monitoring mode — only NEW ads since last run", "type": "boolean", "description": "When ON, the run remembers every ad it has returned before (per monitor) and outputs ONLY ads it has not seen in a previous run. Perfect for scheduled runs: \"what new ads has this advertiser launched since I last checked?\". The first run returns everything (the baseline); later runs return only new ads. In this mode, Max ads caps how many ads are SCANNED per run (max 60), not how many are output. Note that it scans the first N ads Meta returns for your query, which Meta ranks by relevance rather than by date — so monitoring an advertiser's page (a bounded ad set) is far more reliable than monitoring a broad keyword, where a new ad can fall outside the scanned window.", "default": false }, "monitorId": { "title": "Monitor ID (monitoring mode)", "type": "string", "description": "Optional name that ties runs together into one monitor (e.g. \"nike-us\"). Runs sharing a Monitor ID share the same memory of seen ads. Leave blank to auto-derive one from your input — but set it explicitly if you want the monitor to survive small input changes, or to run several independent monitors." }, "pageDelaySeconds": { "title": "Delay between pagination pages", "minimum": 0, "maximum": 60, "type": "integer", "description": "Extra seconds to wait before each pagination request. 0 = automatic pacing: the scraper rotates to a fresh residential IP whenever Meta rate-limits one, which is what large pulls rely on. Raise this (try 5–10) only if a run keeps stopping early with a rate-limit message. The first page of each search is unaffected.", "default": 0 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "REQUIRED. Leave this on Residential. Meta blocks datacenter IPs at the TLS layer, so the scraper needs Apify Residential proxy to reach the Ad Library. The scraper rotates residential IPs automatically when Facebook rate-limits a given IP.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "urlsFromFile": { "title": "Import URLs from a file", "type": "string", "description": "Paste a list of URLs (one per line), OR one link to a .txt/.csv file, Google Sheet or Google Drive file containing them. Lets you import many Start URLs at once instead of typing each. Google Sheet/Drive share links are handled automatically." } } }, "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 } } } } } } } } } }