{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper Monitoring Mode Meta Instagram Ads", "description": "Scrape Facebook, Instagram & Meta ads from the public Meta Ad Library by keyword, Facebook Page, or URL. Get ad copy, creatives, videos, CTA, links, dates & advertiser data — 50+ fields per ad, no login. Monitoring mode returns only NEW ads since your last run. Export JSON, CSV or Excel.", "version": "0.1", "x-build-id": "60djGmnZJI7d51eer" }, "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) or numeric page IDs. Returns ads run by that advertiser. A numeric ID or profile.php?id=… gives exact page targeting; a vanity slug falls back to an advertiser-name search.", "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 first ran on or after this date." }, "dateTo": { "title": "Started on or before", "type": "string", "description": "Only include ads that first ran on or before this date." }, "maxResults": { "title": "Max ads", "minimum": 0, "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.", "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 (cost control), not how many are output.", "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": "Seconds to wait between each pagination request. Meta rate-limits Ad Library pagination aggressively — if a run stops early with a rate-limit message, raise this (try 8–10). The first page of each search is unaffected. Higher = slower but more reliable for large pulls.", "default": 3 }, "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" ] } } } }, "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 } } } } } } } } } }