{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper - Meta Ad Library API + Creatives", "description": "Scrape the Facebook Ads Library (Meta Ad Library) by keyword, advertiser or pasted URL for every ad creative, including the dynamic and carousel variants others drop. Filters are enforced and reported, result caps are exact, and failed or filtered rows are free.", "version": "0.1", "x-build-id": "zJg663zybRsxpbHdW" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/vonsensey~facebook-ads-library-scraper-meta-ad-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-vonsensey-facebook-ads-library-scraper-meta-ad-api", "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/vonsensey~facebook-ads-library-scraper-meta-ad-api/runs": { "post": { "operationId": "runs-sync-vonsensey-facebook-ads-library-scraper-meta-ad-api", "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/vonsensey~facebook-ads-library-scraper-meta-ad-api/run-sync": { "post": { "operationId": "run-sync-vonsensey-facebook-ads-library-scraper-meta-ad-api", "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", "type": "array", "description": "Keywords to search the Ad Library for, one per line. Example: protein powder. Leave empty if you are using Ad Library URLs or advertiser IDs instead — nothing is added to your search.", "items": { "type": "string" } }, "adLibraryUrls": { "title": "Ad Library URLs", "type": "array", "description": "Paste Ad Library URLs straight from your browser. The search term, country, active status and media type in the URL are used as-is, so you do not have to re-enter them below.", "default": [], "items": { "type": "string" } }, "advertiserPageIds": { "title": "Advertiser page IDs", "type": "array", "description": "Scrape every ad from specific advertisers. Accepts a numeric Facebook page ID, or an Ad Library URL containing view_all_page_id.", "default": [], "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Two-letter country codes to search in, or ALL. The Ad Library is country-scoped, so this changes which ads exist.", "default": [ "US" ], "items": { "type": "string" } }, "maxAds": { "title": "Maximum ads (exact)", "minimum": 1, "type": "integer", "description": "Hard cap on billable ads for the whole run. This is exact: the run delivers this many and stops. A call that omits this field gets a small 10-ad sample rather than a large bill; set it explicitly for a real run, or clear it in the Console for no cap.", "default": 10 }, "maxAdsPerTarget": { "title": "Maximum ads per search term", "minimum": 1, "type": "integer", "description": "Optional per-search cap, so one broad keyword cannot consume the whole run." }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Whether to return ads that are currently running, ads that have stopped, or both.", "default": "active" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video" ], "type": "string", "description": "Restrict to image or video ads. This is checked against the creative actually extracted, so it is never silently ignored.", "default": "all" }, "publisherPlatforms": { "title": "Platforms", "type": "array", "description": "Keep only ads shown on at least one of these platforms.", "items": { "type": "string", "enum": [ "FACEBOOK", "INSTAGRAM", "MESSENGER", "THREADS", "WHATSAPP", "AUDIENCE_NETWORK" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Threads", "WhatsApp", "Audience Network" ] }, "default": [] }, "exactPhrase": { "title": "Match the exact phrase", "type": "boolean", "description": "Search for the search term as an exact phrase rather than as unordered keywords.", "default": false }, "startedAfter": { "title": "Started on or after", "type": "string", "description": "ISO date, e.g. 2026-01-31. Ads that started before this are dropped and never charged. An unreadable date is reported as a row, never silently ignored." }, "startedBefore": { "title": "Started on or before", "type": "string", "description": "ISO date, e.g. 2026-06-30. Ads that started after this are dropped and never charged." }, "minDaysRunning": { "title": "Minimum days running", "minimum": 1, "type": "integer", "description": "Keep only ads that have been running at least this long. The usual way to find proven winners: an ad still live after 30+ days is one the advertiser keeps paying for." }, "minCollationCount": { "title": "Minimum ads sharing the creative", "minimum": 1, "type": "integer", "description": "Keep only creatives Meta groups with at least this many near-identical siblings. A high number means the advertiser is scaling that creative." }, "advertiserNameContains": { "title": "Advertiser name contains", "type": "string", "description": "Case-insensitive substring match on the advertiser name." }, "textContains": { "title": "Ad text contains", "type": "string", "description": "Case-insensitive substring match on the ad copy, headline or caption. Dynamic-creative variants are searched too." }, "onlyDynamicCreative": { "title": "Only dynamic-creative ads", "type": "boolean", "description": "Keep only ads whose creative rotates across multiple variants.", "default": false }, "excludeGated": { "title": "Exclude ads Meta has gated", "type": "boolean", "description": "Gated ads are never billed either way; this also removes their free notice rows from the output.", "default": false }, "includeEmptyCreatives": { "title": "Include ads with no creative", "type": "boolean", "description": "Off by default. Ads carrying no media, no text and no link are normally reported as free notice rows rather than billed.", "default": false }, "onlyNew": { "title": "Only new or changed ads", "type": "boolean", "description": "For scheduled monitoring. Remembers what this input already returned and bills only ads that are new, or whose live status, end date or sibling count changed. Rewritten ad copy does not count as a change, so you are never re-billed for a typo fix.", "default": false }, "concurrency": { "title": "Concurrent searches", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many search terms to walk at once.", "default": 3 }, "docId": { "title": "Query ID override", "type": "string", "description": "Advanced. Only needed if Meta ships a new build of the Ad Library and this Actor has not been updated yet." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Leave this exactly as it is. The default is the only configuration this Actor is tested and supported on; changing it will make runs return nothing.", "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 } } } } } } } } } }