{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper — Ad Intelligence", "description": "Scrape Facebook Ads Library creatives, advertisers, copy, media, landing pages, dates, and targeting signals for competitor and campaign research.", "version": "1.0", "x-build-id": "saqf8Orn6EQacUXtV" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/muhammadafzal~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-muhammadafzal-facebook-ads-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/muhammadafzal~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-muhammadafzal-facebook-ads-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/muhammadafzal~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-muhammadafzal-facebook-ads-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 Keywords", "type": "array", "description": "Keywords to search for in the Ad Library (e.g. 'nike', 'running shoes', 'crypto trading'). Each keyword runs as a separate search. Use this when the user provides a topic, niche, or product name to find ads for. Use pageUrls instead when the user provides a specific Facebook Page URL.", "items": { "type": "string" } }, "pageUrls": { "title": "Advertiser Page URLs", "type": "array", "description": "Facebook Page URLs (e.g. https://www.facebook.com/nike) or numeric page IDs. Returns every public ad run by that advertiser. Use this when the user provides a specific brand's Facebook page. Use searchTerms instead when the user wants to search by keyword/topic.", "items": { "type": "string" } }, "adLibraryUrls": { "title": "Ad Library URLs", "type": "array", "description": "Paste full Meta Ad Library URLs (https://www.facebook.com/ads/library/?...) with filters already configured in the URL. Useful when you've set up a search in the Ad Library UI and want to scrape it. Filters encoded in the URL are preserved.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "ALL", "US", "CA", "MX", "BR", "AR", "CL", "CO", "PE", "GB", "IE", "FR", "DE", "ES", "IT", "NL", "BE", "PT", "CH", "AT", "SE", "NO", "DK", "FI", "PL", "CZ", "GR", "RO", "HU", "TR", "IL", "AE", "SA", "EG", "ZA", "NG", "KE", "MA", "IN", "PK", "BD", "ID", "PH", "VN", "TH", "MY", "SG", "JP", "KR", "TW", "HK", "AU", "NZ" ], "type": "string", "description": "Country whose Ad Library to query. Use 'ALL' to search every country at once. Applied to search terms and page URLs. Ad Library URLs use whatever country is encoded in the URL.", "default": "ALL" }, "adActiveStatus": { "title": "Ad Status", "enum": [ "ALL", "ACTIVE", "INACTIVE" ], "type": "string", "description": "Filter by whether ads are currently running. 'ACTIVE' = still being delivered, 'INACTIVE' = stopped, 'ALL' = both.", "default": "ALL" }, "adType": { "title": "Ad Category", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "type": "string", "description": "Meta groups ads into transparency categories. 'ALL' covers every public ad. Political, Housing, Employment, and Credit ads have additional spend/reach disclosures.", "default": "ALL" }, "mediaType": { "title": "Media Type", "enum": [ "ALL", "IMAGE", "VIDEO", "MEME", "NONE" ], "type": "string", "description": "Restrict results by creative format. 'ALL' includes every format.", "default": "ALL" }, "maxResults": { "title": "Max Results", "minimum": 1, "type": "integer", "description": "Maximum number of ads to collect across all sources combined. Set to 0 or leave high for unlimited. Each ad is billed at the 'result-item' rate.", "default": 100 }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings for the scraper. Defaults to Apify residential proxies. If Facebook blocks Apify's shared proxies (403 errors), provide your own premium residential proxy URL (e.g. from Decodo, Bright Data, or IPRoyal) via the proxyConfiguration custom URL field. This is required for reliable scraping — Facebook aggressively blocks shared datacenter and residential proxy pools.", "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 } } } } } } } } } }