{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper", "description": "Scrape the public Facebook Ad Library by keyword or page: advertiser, ad copy, media, CTA, start date and platforms. No login required.", "version": "0.0", "x-build-id": "4U1JiHkbvUF8ZmdDK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bgfc97~facebook-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bgfc97-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/bgfc97~facebook-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-bgfc97-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/bgfc97~facebook-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-bgfc97-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 (advertiser name or keyword)", "type": "array", "description": "List of advertiser names or keywords to search the Facebook Ad Library for, e.g. \"Nike\", \"Coca-Cola\", \"black friday\". Each term is searched separately (keyword_unordered). Leave empty if you instead search by Page ID below. At least one of Search terms or Page IDs is required.", "items": { "type": "string" } }, "pageIds": { "title": "Facebook Page IDs", "type": "array", "description": "List of numeric Facebook Page IDs to pull all of a specific advertiser's library ads (view_all_page_id). Use this when you already know the Page ID (e.g. \"15087023444\"). You can find a Page ID from the Ad Library URL of an advertiser. Leave empty if you search by term above.", "items": { "type": "string" } }, "country": { "title": "Country", "type": "string", "description": "Two-letter ISO country code the Ad Library filters ads by, e.g. \"US\", \"BR\", \"GB\", \"DE\", or \"ALL\" for all countries. The Ad Library always requires a country context; US is a safe default with the most inventory.", "default": "US" }, "adType": { "title": "Ad type", "enum": [ "all", "political" ], "type": "string", "description": "Which slice of the library to search. \"all\" = all ads currently running across Facebook's apps. \"political\" = only political & issue ads (these expose extra data such as spend and impression ranges).", "default": "all" }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Filter by whether the ad is currently running. \"active\" = only ads active right now (default), \"inactive\" = only stopped ads still archived, \"all\" = both active and inactive library ads.", "default": "active" }, "maxItems": { "title": "Max ads (total)", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of ads to collect in total across every search term / Page ID in this run. The scraper scrolls the results to load more until this cap is reached or the library has no more matches. Returns fewer (or zero) honestly rather than padding with fake data.", "default": 30 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Facebook aggressively blocks datacenter IPs and unauthenticated traffic. A RESIDENTIAL proxy group is strongly recommended and used by default — without it, the Ad Library GraphQL requests are very likely blocked or return empty.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "timeoutSecs": { "title": "Per-navigation timeout (seconds)", "minimum": 20, "maximum": 180, "type": "integer", "description": "Timeout for each Ad Library page navigation in the real headless browser. Between 20 and 180 seconds.", "default": 60 } } }, "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 } } } } } } } } } }