{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper: Ads by Keyword or Page ID", "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": "Li7UjSoz8sbhErIZR" }, "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" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "meme", "image_and_meme", "video", "none" ], "type": "string", "description": "Optionally restrict results to a creative media type: \"all\" (default), \"image\", \"meme\", \"image_and_meme\", \"video\", or \"none\" (text-only). Leave as \"all\" to get every creative format.", "default": "all" }, "searchType": { "title": "Keyword match type", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "How a search term is matched (only used for keyword searches). \"keyword_unordered\" (default) matches the words in any order; \"keyword_exact_phrase\" requires the exact phrase. Ignored when searching by Page ID.", "default": "keyword_unordered" }, "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 }, "debugRaw": { "title": "Debug: save one raw ad node", "type": "boolean", "description": "Advanced/debug only. When enabled, the first raw ad node from the Ad Library GraphQL response is saved to the key-value store under DEBUG_RAW_AD so you can inspect every available field. Leave off for normal runs.", "default": false } } }, "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 } } } } } } } } } }