{ "openapi": "3.0.1", "info": { "title": "Meta Facebook Ad Library Scraper", "description": "Meta Facebook Ads Library scraper for keyword, Page, or URL search. Extract ad creatives, advertiser info, spend, and reach as JSON/CSV, no login needed. Also works as a Meta Ads Library scraper and Facebook Ad Library scraping API via Apify.", "version": "1.0", "x-build-id": "fedGfH9faaE7ogHZA" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/code-node-tools~facebook-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-code-node-tools-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/code-node-tools~facebook-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-code-node-tools-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/code-node-tools~facebook-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-code-node-tools-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": { "urls": { "title": "URLs", "type": "array", "description": "List of Facebook Ad Library search URLs or Page URLs to scrape ads from. A search URL (containing ?q=...) is scraped as a keyword search; a URL containing view_all_page_id=, or a plain page URL with a numeric ID, is scraped as that page's ads. Any country / ad_type / active_status / search_type already encoded in the URL overrides the matching setting below. Optional if you use 'queries' and/or 'pageIds' instead.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "queries": { "title": "Search queries", "type": "array", "description": "Keyword searches to run directly, as an alternative or addition to 'urls'. Each query gets its own concurrent session and uses the settings below (country, ad type, active status, sort, date range).", "items": { "type": "string" } }, "pageIds": { "title": "Page IDs", "type": "array", "description": "Numeric Facebook Page IDs to collect all ads from directly, as an alternative or addition to 'urls'. Each Page ID gets its own concurrent session and uses the settings below.", "items": { "type": "string" } }, "limitPerSource": { "title": "Limit per input source", "minimum": 5, "type": "integer", "description": "Maximum number of ads to collect from each individual source (each URL, query, or page ID). Leave blank to collect all available ads per source." }, "count": { "title": "Total number of records required", "minimum": 30, "type": "integer", "description": "Stop the whole run once this many ads have been collected in total, across all URLs/queries/page IDs combined. Leave empty for no overall cap." }, "scrapePageAds.activeStatus": { "title": "Filter ads by active status", "enum": [ "all", "active", "inactive" ], "type": "string", "description": "Whether to collect active ads, inactive ads, or both. Overridden by an active_status value already present in a given URL.", "default": "all" }, "scrapePageAds.sortBy": { "title": "Sort ads by", "enum": [ "impressions_desc", "most_recent" ], "type": "string", "description": "Sort by total impressions or by recency. Applies across all URLs.", "default": "impressions_desc" }, "scrapePageAds.countryCode": { "title": "Filter ads by country", "type": "string", "description": "2-letter ISO country code (ISO 3166-1 alpha-2), e.g. US, IN. Unlike Facebook's own Ad Library site, this Actor requires an exact 2-letter code -- 'ALL' / worldwide is not supported and that source will be skipped with a logged error. Overridden by a country value already present in a given URL.", "default": "US" }, "runTag": { "title": "Run tag", "type": "string", "description": "Optional label stamped onto every output item's 'runTag' field, useful for telling runs apart downstream." }, "pageSize": { "title": "Page size", "minimum": 1, "maximum": 30, "type": "integer", "description": "Ads fetched per API request. Higher means fewer round trips and faster collection. The API caps this around 30.", "default": 30 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "Number of URLs collected in parallel, each with its own session (and its own proxy IP on the platform). This is the main speed lever. Raise it for more throughput, lower it if you start seeing errors.", "default": 20 }, "dedupe": { "title": "Deduplicate ads", "type": "boolean", "description": "Skip ads with an ID already collected earlier in this run. In-memory only (no disk I/O), shared across all concurrent URLs.", "default": true }, "hasVideo": { "title": "Must have video", "type": "boolean", "description": "Leave unset to include both. Set true/false to require or exclude video creatives." }, "useResidentialProxy": { "title": "Use Apify residential proxy", "type": "boolean", "description": "On the Apify platform, routes each session through Apify's residential proxy pool for better reliability at scale. Automatically ignored (never used) when running locally -- local runs always connect directly.", "default": true }, "proxyCountry": { "title": "Proxy country", "type": "string", "description": "Optional two-letter country code to target for residential proxy exit IPs. Leave empty for automatic selection." } } }, "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 } } } } } } } } } }