{ "openapi": "3.0.1", "info": { "title": "Meta (Facebook) Ad Library Scraper", "description": "Scrape the Meta Ad Library by keyword, Facebook Page ID, Ad ID, or direct Ad Library URL. Extract ad copy, CTA, links, images, videos, campaign dates, and other structured data from Facebook and Instagram ads.", "version": "0.0", "x-build-id": "qbdAnDbd6EYD7EwoI" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mikolabs~facebook-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mikolabs-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/mikolabs~facebook-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-mikolabs-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/mikolabs~facebook-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-mikolabs-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": { "startUrls": { "title": "Facebook Ad Library URLs (Direct)", "type": "array", "description": "Provide one or more Facebook Ad Library URLs directly. If provided, all parameter fields below are ignored. Leave empty to build the URL from parameters instead.", "items": { "type": "string" } }, "country": { "title": "Target Country", "type": "string", "description": "ISO 2-letter country code for ad targeting (e.g. US, GB, IN, CA). Required if not using direct URLs.", "default": "US" }, "searchQueries": { "title": "Search Keywords", "type": "array", "description": "List of keywords to search (e.g., 'nike', 'running shoes'). One search is launched concurrently per keyword.", "items": { "type": "string" } }, "pageIds": { "title": "Facebook Page IDs", "type": "array", "description": "List of numeric Page IDs to target specific brands (e.g., 108047081396228). Launches concurrently.", "items": { "type": "string" } }, "adIds": { "title": "Specific Ad IDs", "type": "array", "description": "List of specific numeric Ad IDs to target directly.", "items": { "type": "string" } }, "activeStatus": { "title": "Ad Status Filter", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Filter ads by campaign status (Active, Inactive, or All).", "default": "active" }, "adType": { "title": "Ad Category", "enum": [ "all", "political_and_issue_ads", "housing", "employment", "credit" ], "type": "string", "description": "Filter by Facebook ad categories (e.g. Political, Credit, Housing, or standard ads).", "default": "all" }, "mediaType": { "title": "Media Format Filter", "enum": [ "all", "image", "video", "meme" ], "type": "string", "description": "Scrape ads matching specific media formats (Images, Videos, or Memes).", "default": "all" }, "isTargetedCountry": { "title": "Strict Country Target", "type": "boolean", "description": "Only return ads that specifically target your chosen Target Country.", "default": false }, "contentLanguages": { "title": "Languages", "type": "array", "description": "Restrict results to specific languages (e.g. 'en', 'es', 'it'). Leave blank for all.", "items": { "type": "string" } }, "sortMode": { "title": "Sort Results By", "enum": [ "total_impressions", "relevance", "start_date" ], "type": "string", "description": "Define which metric determines results ordering.", "default": "total_impressions" }, "sortDirection": { "title": "Sort Order Direction", "enum": [ "desc", "asc" ], "type": "string", "description": "Descending (highest first) or Ascending.", "default": "desc" }, "maxItems": { "title": "Maximum Ads to Scrape", "minimum": 1, "type": "integer", "description": "Stop scraping when you hit this total number of ads. The minimum is 1.", "default": 30 }, "maxConcurrency": { "title": "Parallel Browser Tabs", "minimum": 1, "maximum": 10, "type": "integer", "description": "Number of browser tabs to run concurrently. We recommend 1-2 for best stability.", "default": 1 }, "requestHandlerTimeoutSecs": { "title": "Page Scraping Timeout (seconds)", "minimum": 60, "maximum": 1200, "type": "integer", "description": "Max seconds allowed to scroll a single URL. Default of 900 (15m) handles lists with thousands of ads.", "default": 900 }, "proxyConfiguration": { "title": "Proxy Settings", "type": "object", "description": "Residential Proxy is required to bypass Facebook blocks. Select Apify Proxy or use custom proxies.", "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 } } } } } } } } } }