{ "openapi": "3.0.1", "info": { "title": "Facebook & Instagram Ad Library Scraper", "description": "Search Meta's public Ad Library: find any brand's running Facebook & Instagram ads by keyword or page, look up company page IDs, or pull full creative details (copy, images, videos, CTA, landing URL, optional video transcript) by ad ID. No login required, no proxies, no Facebook account needed.", "version": "0.0", "x-build-id": "E1LcVIBSRPRgkL4iX" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/unseenuser~meta-ads/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-unseenuser-meta-ads", "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/unseenuser~meta-ads/runs": { "post": { "operationId": "runs-sync-unseenuser-meta-ads", "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/unseenuser~meta-ads/run-sync": { "post": { "operationId": "run-sync-unseenuser-meta-ads", "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", "required": [ "searchMode", "searchTerms" ], "properties": { "searchMode": { "title": "What do you want to do?", "enum": [ "search_ads", "company_ads", "search_companies", "ad_details" ], "type": "string", "description": "Pick one. The box below changes meaning based on your choice.", "default": "search_ads" }, "searchTerms": { "title": "Search terms", "type": "array", "description": "One per line. What to put here depends on the mode above:\n\n• **Find ads by keyword** — keywords, e.g. `running shoes`, `skincare`\n• **Get all ads from a brand / page** — brand names (e.g. `Nike`) or numeric Facebook page IDs (e.g. `15087023444`). Names are auto-resolved to IDs.\n• **Look up a brand's Facebook page ID** — brand names, e.g. `nike`, `lululemon`\n• **Get full details for a specific ad** — ad IDs (e.g. `702369045530963`) or full Meta Ad Library URLs", "items": { "type": "string" } }, "countries": { "title": "Countries", "uniqueItems": true, "type": "array", "description": "Pick one or more countries. Leave on **All countries** for worldwide. If you select multiple, the actor runs the search once per country and merges results (ScrapeCreators accepts one country at a time).", "items": { "type": "string", "enum": [ "ALL", "US", "GB", "CA", "AU", "NZ", "IE", "DE", "FR", "ES", "IT", "NL", "BE", "CH", "AT", "PT", "DK", "SE", "NO", "FI", "IS", "PL", "CZ", "SK", "HU", "RO", "BG", "GR", "HR", "SI", "EE", "LV", "LT", "LU", "MT", "CY", "BR", "MX", "AR", "CL", "CO", "PE", "VE", "UY", "PY", "BO", "EC", "CR", "PA", "DO", "GT", "HN", "SV", "NI", "CU", "PR", "IN", "JP", "KR", "SG", "MY", "TH", "ID", "PH", "VN", "HK", "TW", "BD", "PK", "LK", "NP", "KH", "LA", "MM", "AE", "SA", "QA", "KW", "BH", "OM", "JO", "LB", "IL", "TR", "EG", "MA", "TN", "DZ", "LY", "SD", "ZA", "NG", "KE", "GH", "ET", "UG", "TZ", "CI", "CM", "SN", "MU", "RW", "ZM", "ZW", "AO", "MZ", "BW", "NA", "RU", "UA", "BY", "MD", "GE", "AM", "AZ", "KZ", "UZ", "KG", "TJ", "TM", "MN", "RS", "BA", "MK", "AL", "ME", "XK", "FJ", "PG", "NC", "SB", "VU", "WS", "TO" ], "enumTitles": [ "All countries", "United States", "United Kingdom", "Canada", "Australia", "New Zealand", "Ireland", "Germany", "France", "Spain", "Italy", "Netherlands", "Belgium", "Switzerland", "Austria", "Portugal", "Denmark", "Sweden", "Norway", "Finland", "Iceland", "Poland", "Czechia", "Slovakia", "Hungary", "Romania", "Bulgaria", "Greece", "Croatia", "Slovenia", "Estonia", "Latvia", "Lithuania", "Luxembourg", "Malta", "Cyprus", "Brazil", "Mexico", "Argentina", "Chile", "Colombia", "Peru", "Venezuela", "Uruguay", "Paraguay", "Bolivia", "Ecuador", "Costa Rica", "Panama", "Dominican Republic", "Guatemala", "Honduras", "El Salvador", "Nicaragua", "Cuba", "Puerto Rico", "India", "Japan", "South Korea", "Singapore", "Malaysia", "Thailand", "Indonesia", "Philippines", "Vietnam", "Hong Kong", "Taiwan", "Bangladesh", "Pakistan", "Sri Lanka", "Nepal", "Cambodia", "Laos", "Myanmar", "United Arab Emirates", "Saudi Arabia", "Qatar", "Kuwait", "Bahrain", "Oman", "Jordan", "Lebanon", "Israel", "Turkey", "Egypt", "Morocco", "Tunisia", "Algeria", "Libya", "Sudan", "South Africa", "Nigeria", "Kenya", "Ghana", "Ethiopia", "Uganda", "Tanzania", "Ivory Coast", "Cameroon", "Senegal", "Mauritius", "Rwanda", "Zambia", "Zimbabwe", "Angola", "Mozambique", "Botswana", "Namibia", "Russia", "Ukraine", "Belarus", "Moldova", "Georgia", "Armenia", "Azerbaijan", "Kazakhstan", "Uzbekistan", "Kyrgyzstan", "Tajikistan", "Turkmenistan", "Mongolia", "Serbia", "Bosnia & Herzegovina", "North Macedonia", "Albania", "Montenegro", "Kosovo", "Fiji", "Papua New Guinea", "New Caledonia", "Solomon Islands", "Vanuatu", "Samoa", "Tonga" ] }, "default": [ "ALL" ] }, "status": { "title": "Ad status", "enum": [ "ACTIVE", "INACTIVE", "ALL" ], "type": "string", "description": "Only show ads that are currently running, or include paused/ended ads too.", "default": "ACTIVE" }, "maxItems": { "title": "Maximum ads to return (total)", "minimum": 0, "type": "integer", "description": "Stops the run once this many ads are collected across **all** search terms. Use `0` for no limit. By default this budget is split evenly across your terms (e.g. 100 items / 8 terms ≈ 13 per term).", "default": 100 }, "maxItemsPerTerm": { "title": "Maximum ads per search term", "minimum": 0, "type": "integer", "description": "Hard cap for each individual search term. Use `0` (default) to auto-distribute the total budget evenly across your terms. Set an explicit number (e.g. `20`) if you want the same cap per term regardless of how many terms you add.", "default": 0 }, "mediaType": { "title": "Media type", "enum": [ "ALL", "IMAGE", "VIDEO", "MEME", "IMAGE_AND_MEME", "NONE" ], "type": "string", "description": "Filter by creative format.", "default": "ALL" }, "sortBy": { "title": "Sort by", "enum": [ "total_impressions", "relevancy_monthly_grouped" ], "type": "string", "description": "Applies to ad-returning modes.", "default": "total_impressions" }, "startDate": { "title": "Start date", "type": "string", "description": "Only include ads running on or after this date. Click to pick from a calendar." }, "endDate": { "title": "End date", "type": "string", "description": "Only include ads running on or before this date. Click to pick from a calendar." }, "searchType": { "title": "Keyword match", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "Only used when finding ads by keyword.", "default": "keyword_unordered" }, "languages": { "title": "Languages", "uniqueItems": true, "type": "array", "description": "Click to pick one or more languages to filter ads by. Only used when getting ads from a brand/page. Leave empty for no language filter. Multiple languages will fan out (one API call per language).", "items": { "type": "string", "enum": [ "EN", "ES", "FR", "DE", "IT", "PT", "NL", "PL", "RU", "UK", "TR", "AR", "HE", "FA", "ZH", "JA", "KO", "VI", "TH", "ID", "MS", "HI", "BN", "UR", "TA", "TE", "SV", "NO", "DA", "FI", "IS", "CS", "SK", "HU", "RO", "BG", "EL", "HR", "SR", "SL", "ET", "LV", "LT", "SW", "AM", "YO", "ZU", "AF", "CA", "EU", "GL", "GA", "CY" ], "enumTitles": [ "English", "Spanish", "French", "German", "Italian", "Portuguese", "Dutch", "Polish", "Russian", "Ukrainian", "Turkish", "Arabic", "Hebrew", "Persian", "Chinese", "Japanese", "Korean", "Vietnamese", "Thai", "Indonesian", "Malay", "Hindi", "Bengali", "Urdu", "Tamil", "Telugu", "Swedish", "Norwegian", "Danish", "Finnish", "Icelandic", "Czech", "Slovak", "Hungarian", "Romanian", "Bulgarian", "Greek", "Croatian", "Serbian", "Slovenian", "Estonian", "Latvian", "Lithuanian", "Swahili", "Amharic", "Yoruba", "Zulu", "Afrikaans", "Catalan", "Basque", "Galician", "Irish", "Welsh" ] }, "default": [] }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads" ], "type": "string", "description": "Restrict to political / issue ads (they come with extra fields like spend and audience). Only used when finding ads by keyword.", "default": "all" }, "getTranscript": { "title": "Include video transcript", "type": "boolean", "description": "Only used in 'Get full details for a specific ad'. Works on videos under 2 minutes.", "default": false }, "trim": { "title": "Smaller response", "type": "boolean", "description": "Strip rarely-used fields from each ad for a lighter dataset.", "default": false }, "maxPagesPerQuery": { "title": "Max pages per term", "minimum": 1, "type": "integer", "description": "Safety cap on pagination per search term. Default 100 is plenty.", "default": 100 } } }, "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 } } } } } } } } } }