{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper", "description": "Scrape the Meta (Facebook & Instagram) Ad Library by keyword, Facebook Page or Ad Library URL. Get every ad's text, images, videos, dates, platforms and advertiser.", "version": "0.0", "x-build-id": "2E7JHiuK6KZ6TMvAr" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/alkausari_mujahid~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-alkausari_mujahid-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/alkausari_mujahid~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-alkausari_mujahid-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/alkausari_mujahid~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-alkausari_mujahid-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": { "searchQueries": { "title": "Keywords", "type": "array", "description": "Words or phrases to search the Ad Library for, one per line — brand names, products, topics. Each keyword is a separate search.", "items": { "type": "string" } }, "pages": { "title": "Facebook Pages", "type": "array", "description": "Get all ads of these advertisers. Paste a Facebook Page URL (facebook.com/nike), a username (nike) or a page ID (15087023444), one per line.", "items": { "type": "string" } }, "startUrls": { "title": "Ad Library URLs", "type": "array", "description": "Paste searches straight from facebook.com/ads/library — set the filters on the website, then copy the URL. The URL's own filters are used. A single-ad link (…/ads/library/?id=123) returns that ad.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxAdsPerSearch": { "title": "Max ads per search", "minimum": 0, "type": "integer", "description": "How many ads to save for each keyword, Page or URL. Set 0 to get every ad Facebook shows.", "default": 100 }, "country": { "title": "Country", "enum": [ "ALL", "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "CV", "KH", "CM", "CA", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CK", "CR", "CI", "HR", "CW", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "HU", "IS", "IN", "ID", "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", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "RE", "RO", "RW", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "SD", "SR", "SJ", "SE", "CH", "TW", "TJ", "TZ", "TH", "BS", "GM", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "VI", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VA", "VE", "VN", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "Only ads shown in this country. \"All countries\" searches everywhere. Used for keywords and Pages; Ad Library URLs keep their own country.", "default": "ALL" }, "activeStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Active ads are running now. Inactive ads are kept by Facebook only for political/issue ads, and for ads shown in the EU (for one year).", "default": "active" }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads" ], "type": "string", "description": "Limit to one of Facebook's special ad categories.", "default": "all" }, "keywordMatch": { "title": "Keyword match", "enum": [ "any", "exact" ], "type": "string", "description": "\"Any words\" finds ads containing all the words in any order. \"Exact phrase\" finds the exact phrase only.", "default": "any" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "meme", "image_and_meme", "video", "none" ], "type": "string", "description": "Only ads with this kind of creative.", "default": "all" }, "platforms": { "title": "Platforms", "type": "array", "description": "Only ads that ran on these platforms. Leave empty for all.", "items": { "type": "string", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads" ] }, "default": [] }, "languages": { "title": "Ad languages", "type": "array", "description": "Only ads in these languages, as two-letter codes (en, es, de…). Leave empty for all.", "default": [], "items": { "type": "string" } }, "dateFrom": { "title": "Shown from", "type": "string", "description": "Only ads that were shown on or after this date." }, "dateTo": { "title": "Shown until", "type": "string", "description": "Only ads that were shown on or before this date." }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "newest", "impressions" ], "type": "string", "description": "\"Relevance\" is the Ad Library's default order. \"Newest first\" shows the most recently started ads first — best with \"Only new ads\". \"Most impressions\" puts the ads seen by the most people first.", "default": "relevance" }, "onlyNewAds": { "title": "Only new ads (for scheduled runs)", "type": "boolean", "description": "Save only ads this search hasn't returned in earlier runs. Schedule the Actor (e.g. daily) to get just the new ads each time. Works best with \"Sort by: Newest first\". The first run saves everything up to the limit.", "default": false }, "saveMedia": { "title": "Save images and videos", "enum": [ "none", "images", "all" ], "type": "string", "description": "Facebook's image and video links expire after about 4 days. Turn this on to copy the files to the run's storage, with permanent links in the mediaFiles field.", "default": "none" }, "includeAdDetails": { "title": "Include EU ad details and advertiser profile", "type": "boolean", "description": "For each ad, also get the Ad Library's transparency panel: who paid for it, who it targeted (locations, gender, ages), EU reach by country, age and gender, plus the advertiser's Instagram username, followers and verification. One extra request per ad, so runs take longer. EU reach and targeting exist only for ads shown in the EU.", "default": false }, "includeRawData": { "title": "Include Facebook's raw ad data", "type": "boolean", "description": "Add the complete, unprocessed ad object from Facebook under the raw field.", "default": false }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Keep Apify residential proxy. Facebook refuses ad results to datacenter IPs, so without residential each search stops after its first ~30 ads. Pages still load directly to keep proxy traffic low.", "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 }, "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 } } } } } } } } } }