{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper: Meta Ads, Spend & Media", "description": "Get ads from the Meta (Facebook) Ad Library by keyword, advertiser page or library link: texts, images, videos, dates, platforms and versions, plus spend for political ads. Monitor new ads.", "version": "0.1", "x-build-id": "TnGjCm6zp7PdWzBtK" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/stratumics~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-stratumics-facebook-ads-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/stratumics~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-stratumics-facebook-ads-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/stratumics~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-stratumics-facebook-ads-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", "type": "array", "description": "Words to search the Ad Library for, one per line, as in the library's search box. Put a term in double quotes (\"running shoes\") to match the exact phrase.", "default": [], "items": { "type": "string" } }, "searchType": { "title": "Match search terms", "enum": [ "keyword", "exactPhrase" ], "type": "string", "description": "Any of the words (the library's keyword search) or the exact phrase.", "default": "keyword" }, "pageUrls": { "title": "Facebook pages", "type": "array", "description": "Advertisers to list every ad of: Facebook page links (facebook.com/nike, facebook.com/profile.php?id=...) or numeric page ids, one per line.", "default": [], "items": { "type": "string" } }, "libraryUrls": { "title": "Ad Library links", "type": "array", "description": "Links copied from facebook.com/ads/library after setting filters there; each keeps its own search and filters (the filters below do not change them). A link to one ad (?id=...) saves that ad.", "default": [], "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "ALL", "AF", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "DY", "BM", "BT", "BO", "BA", "BW", "BR", "VG", "BN", "BG", "BF", "HV", "BI", "KH", "CM", "CA", "CV", "BQ", "KY", "CF", "TD", "CL", "CN", "CO", "KM", "CG", "CD", "ZR", "CK", "CR", "CI", "HR", "CU", "AN", "CW", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "FX", "GF", "PF", "GA", "GM", "GE", "DD", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "BU", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "KP", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PL", "PT", "PR", "QA", "RE", "RO", "RU", "SU", "RW", "WS", "SM", "ST", "SA", "SN", "CS", "RS", "YU", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "KR", "SS", "ES", "LK", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "SD", "SR", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TP", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "VI", "UG", "UA", "AE", "GB", "UK", "US", "UY", "UZ", "NH", "VU", "VA", "VE", "VD", "VN", "WF", "EH", "YD", "YE", "ZM", "RH", "ZW" ], "type": "string", "description": "Where the ads were shown. All countries by default.", "default": "ALL" }, "adCategory": { "title": "Ad category", "enum": [ "all", "political", "housing", "employment", "credit" ], "type": "string", "description": "All ads, or one of the library's special categories. Political and issue ads come with spend, impressions and the \"Paid for by\" disclaimer.", "default": "all" }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Ads running now, ads that stopped, or both.", "default": "active" }, "platforms": { "title": "Platforms", "type": "array", "description": "Only ads shown on these platforms. Leave empty for all.", "items": { "type": "string", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads", "whatsapp" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads", "WhatsApp" ] }, "default": [] }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ], "type": "string", "description": "Only ads with this kind of media.", "default": "all" }, "languages": { "title": "Ad languages", "type": "array", "description": "Only ads in these languages, as codes such as en, es or de. Leave empty for all.", "default": [], "items": { "type": "string" } }, "dateFrom": { "title": "Shown from", "type": "string", "description": "Only ads shown on or after this date (the library's impressions date filter)." }, "dateTo": { "title": "Shown until", "type": "string", "description": "Only ads shown on or before this date." }, "maxAdsPerInput": { "title": "Maximum ads per input", "minimum": 1, "maximum": 50000, "type": "integer", "description": "How many ads to read for each search term, page and Ad Library link. The library lists ads by relevance, not by date.", "default": 100 }, "includeEuTransparency": { "title": "Add EU reach and audience", "type": "boolean", "description": "For ads shown in the EU, read the ad's details too: total EU reach, reach by country, age and gender, the targeted ages, gender and places, and the payer and beneficiary. Takes one more request per such ad.", "default": false }, "onlyNewAds": { "title": "Only new ads", "type": "boolean", "description": "Save only ads earlier runs with the same inputs have not returned. The library lists ads by relevance, so each run still reads the whole list up to the maximum below; ads it already saved before are skipped and cost $0.05 per 1,000 instead of the full ad price. The Actor remembers ad ids in the key-value store facebook-ads-library-monitor in your account. Pair it with a schedule for competitor alerts.", "default": false }, "monitorName": { "title": "Monitor name", "type": "string", "description": "Optional. A name for the remembered list, so different schedules keep separate histories even with the same inputs. Leave empty to derive it from the inputs.", "default": "" }, "maxConcurrency": { "title": "Inputs at once", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many inputs are read at the same time. Each input's pages are read one after another.", "default": 5 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Leave Apify Proxy on: the Actor then loads library pages over Apify datacenter proxy and the search pages after them over Apify residential proxy, which Facebook requires; both are included in the price. Pick proxy groups or your own proxy URLs to send every request through them instead.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } }