{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper", "description": "Scrape Facebook Ad Library ads by keyword, page URL or domain and find the competitor ads that keep running. Get days running, a 0-100 winner score, variant count, landing domain and UTMs, EU reach, political spend and new or stopped ad alerts.", "version": "0.1", "x-build-id": "2iVNol0GoDPCC2TTJ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cliqtomedia~facebook-ad-library/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cliqtomedia-facebook-ad-library", "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/cliqtomedia~facebook-ad-library/runs": { "post": { "operationId": "runs-sync-cliqtomedia-facebook-ad-library", "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/cliqtomedia~facebook-ad-library/run-sync": { "post": { "operationId": "run-sync-cliqtomedia-facebook-ad-library", "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, domains or Ad Library links", "type": "array", "description": "Keywords (\"running shoes\"), website domains (\"nike.com\") or pasted Ad Library search links. Each entry is one search per country. Up to 50.", "items": { "type": "string" } }, "pageUrls": { "title": "Advertiser pages or ad IDs", "type": "array", "description": "Facebook page links (facebook.com/nike), numeric page IDs (15087023444), or single-ad links (facebook.com/ads/library/?id=…). Lists every ad of that advertiser. Up to 50.", "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Two-letter country codes where the ads are shown (US, GB, DE, …), or ALL for every country. Each country is a separate search. Up to 10.", "default": [ "US" ], "items": { "type": "string" } }, "activeStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Which ads to return. Facebook keeps inactive commercial ads in the library for a limited time; political ads for 7 years.", "default": "active" }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads" ], "type": "string", "description": "Ad Library category. Political ads include spend ranges and the \"Paid for by\" disclaimer.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "none" ], "type": "string", "description": "Keep only ads with this kind of creative.", "default": "all" }, "maxAds": { "title": "Max ads per search", "minimum": 1, "maximum": 3000, "type": "integer", "description": "Stop each search (one term or page in one country) after this many ads. You pay per ad delivered.", "default": 100 }, "sortBy": { "title": "Sort results", "enum": [ "source", "winnerScore", "longestRunning", "newest" ], "type": "string", "description": "Order of the ads inside each search. Sorting applies to the ads collected up to Max ads.", "default": "source" }, "includeAdDetails": { "title": "Add EU reach, demographics and payer details", "type": "boolean", "description": "For each ad, open the Ad Library detail panel: EU and UK reach, age and gender breakdown, target locations, payer and beneficiary, page verification and Instagram followers. Charged as an extra event per ad that returns details.", "default": false }, "saveMedia": { "title": "Save ad images to storage", "type": "boolean", "description": "Download the first image (or video thumbnail) of each ad into the run's key-value store, because Facebook image links expire. Charged per saved file.", "default": false }, "trackChanges": { "title": "Track new and stopped ads", "type": "boolean", "description": "Remember which ads each search returned. Every ad gets changeStatus new or seen, and the CHANGES record lists ads that stopped since the last run. Use with a schedule to monitor competitors.", "default": false }, "onlyNew": { "title": "Only new ads", "type": "boolean", "description": "Deliver only ads not seen by the same search in earlier runs. Each skipped, already seen ad costs a small ad-checked fee instead of the full ad price. Turns on change tracking.", "default": false }, "stateName": { "title": "Tracking memory name", "type": "string", "description": "Name of the key-value store that keeps the tracking memory. Use different names for independent monitors. Lowercase letters, digits and hyphens.", "default": "facebook-ad-library-state" }, "includeAdvertiserSummary": { "title": "Advertiser comparison summary", "type": "boolean", "description": "Write an ADVERTISER_SUMMARY record: per advertiser ad count, average days running and winner score, top ads, formats, platforms, CTAs and landing domains. Put 2–3 competitors in one run to compare them. Free.", "default": false }, "outputFormat": { "title": "Row format", "enum": [ "flat", "nested" ], "type": "string", "description": "Flat puts every field in its own column. Nested groups fields into advertiser, creative, link, metrics, analysis and details objects.", "default": "flat" }, "proxyConfiguration": { "title": "Proxy for search pages, details and images", "type": "object", "description": "Proxy used to open the Ad Library search page, ad details and images. The default (Apify Proxy, automatic datacenter IPs) works for most runs. Next result pages always go through Apify residential IPs of the search country, because Facebook limits them from datacenter IPs. If a datacenter request keeps failing, the Actor retries it through residential IPs.", "default": { "useApifyProxy": true } }, "deliveryConnector": { "title": "Send results to (optional)", "type": "string", "description": "Your Slack, Notion or other MCP connector. After the run the Actor posts a short summary there. Connect services once in Apify Console → MCP connectors." }, "deliveryTarget": { "title": "Notion page or channel (optional)", "type": "string", "description": "Where to post the summary: a Notion page link (each run is added on top of that page) or a Slack channel ID. Leave empty to let the connector decide." } } }, "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 } } } } } } } } } }