{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper", "description": "Scrape ads from the Meta Ad Library by keyword, Page ID or Ad Library URL. Ad copy, CTA, links, image and video URLs, dates, platforms, plus optional EU reach and payer/beneficiary data.", "version": "0.1", "x-build-id": "S8FH0TWGMQbmsx3aI" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sarel-data~facebook-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sarel-data-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/sarel-data~facebook-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-sarel-data-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/sarel-data~facebook-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-sarel-data-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", "type": "array", "description": "Keywords to search, one per line. Each term is a separate search.", "items": { "type": "string" } }, "pageIds": { "title": "Facebook Page IDs", "type": "array", "description": "Numeric Page IDs (or Ad Library URLs containing view_all_page_id=). Returns every ad the Page runs.", "items": { "type": "string" } }, "startUrls": { "title": "Ad Library URLs", "type": "array", "description": "Paste any search URL from facebook.com/ads/library. Filters in the URL are used as-is and override the filters below.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code (US, GB, FR, DE...) or ALL.", "default": "US" }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "financial_products_and_services_ads" ], "type": "string", "description": "Ad category", "default": "all" }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Active status", "default": "active" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ], "type": "string", "description": "Media type", "default": "all" }, "searchType": { "title": "Keyword matching", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "Keyword matching", "default": "keyword_unordered" }, "platforms": { "title": "Platforms", "type": "array", "description": "Leave empty for all platforms.", "items": { "type": "string", "enum": [ "facebook", "instagram", "audience_network", "messenger", "threads" ], "enumTitles": [ "Facebook", "Instagram", "Audience Network", "Messenger", "Threads" ] } }, "startDateMin": { "title": "Ran on or after", "type": "string", "description": "Facebook's own date filter: keeps ads that were delivering on or after this date (YYYY-MM-DD). Combine with \"Filter by start date\" for ads that *started* in the range." }, "startDateMax": { "title": "Ran on or before", "type": "string", "description": "Keeps ads that were delivering on or before this date (YYYY-MM-DD)." }, "strictStartDate": { "title": "Filter by start date", "type": "boolean", "description": "Also drop ads whose start date is outside the range above (e.g. long-running ads that started earlier).", "default": false }, "sortBy": { "title": "Sort", "enum": [ "relevancy", "total_impressions" ], "type": "string", "description": "Sort", "default": "relevancy" }, "maxItems": { "title": "Max ads per input", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Upper limit of ads saved for each search term / Page / URL. You are only charged for ads saved.", "default": 100 }, "includeAdDetails": { "title": "Include EU transparency & advertiser details", "type": "boolean", "description": "Adds EU reach (total and by age/gender/country), targeting, payer/beneficiary, page spend and Instagram info. Most useful with EU countries. Slower: one extra request per ad.", "default": false }, "deduplicateAcrossInputs": { "title": "Deduplicate across inputs", "type": "boolean", "description": "Save an ad only once even if several inputs return it.", "default": true }, "directFirst": { "title": "Try direct connection first", "type": "boolean", "description": "Connect without a proxy first and use the proxy below only after a block. Turn off to send all traffic through the proxy.", "default": true }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Fallback proxy. By default the scraper connects directly (cheapest) and only switches to this proxy when Facebook blocks a request. Residential is recommended as the fallback.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "maxConcurrency": { "title": "Parallel browsers", "minimum": 1, "maximum": 20, "type": "integer", "description": "Parallel browsers", "default": 3 }, "maxRequestRetries": { "title": "Retries per input", "minimum": 0, "maximum": 20, "type": "integer", "description": "Each retry uses a fresh browser session and proxy IP.", "default": 6 } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }