{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper: Meta Ad Spy Tool", "description": "Scrape Facebook & Instagram ads from Meta Ad Library by keyword, page or URL. Get ad copy, creatives, carousel cards, CTA links, EU spend, impressions, age/gender audience reach and running-days per ad. Filter by country, language, status. For ad spy, dropshipping, agencies. $0.75/1K ads.", "version": "1.0", "x-build-id": "ZMeBM6HprwcCoMpJz" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dltik~facebook-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dltik-facebook-ads-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/dltik~facebook-ads-scraper/runs": { "post": { "operationId": "runs-sync-dltik-facebook-ads-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/dltik~facebook-ads-scraper/run-sync": { "post": { "operationId": "run-sync-dltik-facebook-ads-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": { "urls": { "title": "Ad Library URLs", "type": "array", "description": "List of Meta Ad Library URLs or Facebook page ad URLs. Supports search results URLs, page URLs, and filtered URLs. Process multiple URLs in one run.", "items": { "type": "string" } }, "searchTerms": { "title": "Search keywords", "type": "string", "description": "Keywords to search in ad text (e.g. 'fitness', 'nike', 'skincare'). Alternative to pasting an Ad Library URL." }, "pageId": { "title": "Facebook Page ID", "type": "string", "description": "View all ads from a specific Facebook page. Get the page ID from the page URL or About section." }, "country": { "title": "Country", "type": "string", "description": "ISO 2-letter country code (US, FR, GB, DE, etc.). Use 'ALL' for worldwide.", "default": "ALL" }, "activeStatus": { "title": "Ad status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Filter by active, inactive, or all ads.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme" ], "type": "string", "description": "Filter by media type: all, image, video, or meme.", "default": "all" }, "contentLanguages": { "title": "Content languages", "type": "array", "description": "Filter ads by language (ISO 639-1 codes, e.g. ['en', 'fr']). Leave empty for all languages.", "items": { "type": "string" } }, "sortMode": { "title": "Sort by", "enum": [ "relevance", "total_impressions", "start_date" ], "type": "string", "description": "Preferred sort (relevance, total impressions, or start date). Best-effort: the Facebook Ad Library frequently overrides custom sort with its own relevance ranking, so results may not strictly follow the requested order. Sorting never changes WHICH ads are returned, only their (attempted) order.", "default": "relevance" }, "sortDirection": { "title": "Sort direction", "enum": [ "desc", "asc" ], "type": "string", "description": "Sort ascending or descending.", "default": "desc" }, "maxResults": { "title": "Max results per URL", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of ads to extract per URL. Initial page load gives ~28 ads. More requires scrolling.", "default": 50 }, "enrichAds": { "title": "Enrich ads with analysis", "type": "boolean", "description": "Add CTA detection, ad category (ecommerce/lead_gen/app_install), running duration, hashtag count, word count, and a winner_score (0-100) flagging proven performers by longevity + variants + still-active.", "default": true }, "analyzeAds": { "title": "AI angle analysis (premium)", "type": "boolean", "description": "Use AI to classify each ad's marketing angle, emotional hook, offer type and target persona. Paid Apify plan only. Billed per ad analyzed.", "default": false }, "transcribeVideos": { "title": "Transcribe video ads (premium)", "type": "boolean", "description": "Transcribe the audio of each video ad so you can read the script/hook of winning video creatives. Paid Apify plan only. Billed per video transcribed.", "default": false }, "maxConcurrency": { "title": "Max parallel URLs", "minimum": 1, "maximum": 8, "type": "integer", "description": "How many URLs to scrape in parallel. Higher = faster on multi-URL/multi-brand runs, each on its own residential IP. Kept to 8 max so the browser fallback stays within the 512MB memory limit.", "default": 4 }, "useResidentialProxy": { "title": "Use residential proxy (deep pagination)", "type": "boolean", "description": "Route requests through residential IPs. Required to fetch more than ~30 ads per search (Facebook rate-limits pagination per IP). Disable to run free on datacenter IPs at ~30 ads/URL.", "default": true }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Advanced: override the proxy. Defaults to Apify residential proxy in the search country. Leave empty to use the recommended default.", "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 } } } } } } } } } }