{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Full Scraper", "description": "Pull complete ad records from Meta's public Ad Library: full ad copy, headline, CTA, destination URL, every image and video creative including carousel cards, flight dates, days on air, platforms and advertiser. Search by keyword or advertiser, any country. Paginates past the first 30.", "version": "0.0", "x-build-id": "kPsTk5BcRkqSlSrFM" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/fanndev~facebook-ad-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-fanndev-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/fanndev~facebook-ad-library-scraper/runs": { "post": { "operationId": "runs-sync-fanndev-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/fanndev~facebook-ad-library-scraper/run-sync": { "post": { "operationId": "run-sync-fanndev-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": "Keywords", "type": "array", "description": "One keyword or phrase per line. Each is searched in every country you list below, so 3 keywords x 2 countries = 6 searches.", "items": { "type": "string" } }, "advertisers": { "title": "Advertisers (Ad Library page URLs or page ids)", "type": "array", "description": "Pull every ad from a specific advertiser. Paste the Ad Library URL of the advertiser (the one containing view_all_page_id=...) or just the numeric page id. A plain facebook.com/ URL will NOT work here: the Ad Library addresses advertisers by numeric id only, and this actor tells you rather than silently returning nothing.", "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "ISO country codes to search. The Ad Library is country-scoped, so a term with no ads in one country legitimately returns zero there.", "default": [ "US" ], "items": { "type": "string" } }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads", "employment_ads", "housing_ads", "credit_ads", "financial_products_and_services_ads" ], "type": "string", "description": "'All ads' covers commercial advertising. The political & issue category is the only one where Facebook publishes spend and impression ranges - for every other category those fields come back empty, by Meta's policy and not because they were missed.", "default": "all" }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Whether to return ads currently running, ads that have stopped, or both.", "default": "active" }, "searchType": { "title": "Keyword match", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "Unordered matches the words in any order; exact phrase matches the phrase as typed.", "default": "keyword_unordered" }, "mediaType": { "title": "Creative type", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ], "type": "string", "description": "Restrict to image, video or meme creatives.", "default": "all" }, "publisherPlatforms": { "title": "Platforms", "type": "array", "description": "Restrict to ads delivered on these Meta surfaces. Leave empty for all of them.", "items": { "type": "string", "enum": [ "FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER", "WHATSAPP", "THREADS" ] }, "default": [] }, "contentLanguages": { "title": "Ad languages", "type": "array", "description": "Two-letter language codes, e.g. en, id, es. Leave empty for any language.", "default": [], "items": { "type": "string" } }, "startDateFrom": { "title": "First shown on or after", "type": "string", "description": "YYYY-MM-DD. Filters on the day the ad started running." }, "startDateTo": { "title": "First shown on or before", "type": "string", "description": "YYYY-MM-DD." }, "maxAdsPerQuery": { "title": "Max ads per search", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Facebook server-renders the first 30 ads; anything beyond that is fetched by replaying its own pagination query, 30 at a time. Keep this low while you are tuning a search.", "default": 60 }, "onlyActive": { "title": "Only ads still running", "type": "boolean", "description": "Drop ads Facebook reports as no longer active.", "default": false }, "onlyWithVideo": { "title": "Only ads with video", "type": "boolean", "description": "Keep only creatives that carry at least one video file.", "default": false }, "minRunningDays": { "title": "Minimum days on air", "minimum": 0, "type": "integer", "description": "Long-running ads are the ones an advertiser kept paying for. Ads with no usable flight dates are dropped rather than admitted on a guess." }, "adTextContains": { "title": "Ad copy contains", "type": "string", "description": "Case-insensitive substring match across the ad body, headline, caption and link description." }, "emitSummary": { "title": "Add a run summary record", "type": "boolean", "description": "Append one RUN_SUMMARY record: ads collected, how many are active, how many advertisers and the median days on air.", "default": true }, "exportFormats": { "title": "Extra export files", "type": "array", "description": "Also write the results to the key-value store in these formats. The dataset is always produced regardless.", "items": { "type": "string", "enum": [ "json", "ndjson", "csv", "xlsx" ], "enumTitles": [ "JSON", "NDJSON", "CSV", "Excel (XLSX)" ] }, "default": [] }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Optional. The Ad Library's HTTP 403 is a verification challenge this actor solves on its own, not an IP block, so the direct connection works. Use a proxy only to spread a very large run across IPs, or to see a country's library from inside that country.", "default": { "useApifyProxy": 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 } } } } } } } } } }