{ "description": "Search the Facebook Ad Library by keyword, advertiser Page, Ad Library ID, or \"Paid for by\" name. Returns ad creative, media, run dates, platforms, political spend/impressions and EU transparency reach. No login, cookies or Meta API token required.", "properties": { "adActiveStatus": { "default": "active", "description": "Filter by ad active status.", "editor": "select", "enum": [ "all", "active", "inactive" ], "enumTitles": [ "All Ads", "Active Only", "Inactive Only" ], "prefill": "active", "title": "Ad Status", "type": "string" }, "adIds": { "description": "Ad Library IDs to fetch directly (numeric IDs or Ads Library URLs containing ?id=). All other filters are ignored in this mode.", "editor": "stringList", "items": { "type": "string" }, "title": "Direct Ad IDs", "type": "array" }, "adType": { "default": "all", "description": "Filter by ad category. Note: the political-and-issue archive excludes EU/EEA countries, so EU political searches automatically use All Types (EU transparency stream).", "editor": "select", "enum": [ "all", "political_and_issue_ads", "housing", "employment", "credit" ], "enumTitles": [ "All Types", "Political & Issue Ads", "Housing", "Employment", "Credit" ], "prefill": "all", "title": "Ad Type", "type": "string" }, "bylines": { "description": "Funding-entity / committee names from the \"Paid for by\" disclaimer on political and issue ads. Matching is exact (case-insensitive fallback): use the name as it appears in the ad. Byline targets always search the political & issue archive, since the Ad Library ignores this filter elsewhere.", "editor": "stringList", "items": { "type": "string" }, "title": "Search by \"Paid for by\" name", "type": "array" }, "contentLanguages": { "description": "2-letter ISO language codes (e.g. en, de, es) to restrict ads by creative language.", "editor": "stringList", "items": { "type": "string" }, "title": "Ad Content Languages", "type": "array" }, "countries": { "description": "One or more country codes, searched together as a union (unlike the single Country field). Takes precedence over Country when set.", "editor": "select", "items": { "enum": [ "ALL", "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BR", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CO", "KM", "CG", "CD", "CR", "HR", "CU", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FJ", "FI", "FR", "GF", "PF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GN", "GW", "GY", "HT", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IL", "IT", "JM", "JP", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "MK", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PL", "PT", "PR", "QA", "RO", "RU", "RW", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SK", "SI", "SB", "SO", "ZA", "KR", "SS", "ES", "LK", "KN", "LC", "VC", "SD", "SR", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UY", "UZ", "VU", "VA", "VE", "VN", "VG", "VI", "YE", "ZM", "ZW" ], "enumTitles": [ "All Countries", "Afghanistan", "Albania", "Algeria", "American Samoa", "Andorra", "Angola", "Anguilla", "Antarctica", "Antigua and Barbuda", "Argentina", "Armenia", "Aruba", "Australia", "Austria", "Azerbaijan", "Bahamas", "Bahrain", "Bangladesh", "Barbados", "Belarus", "Belgium", "Belize", "Benin", "Bermuda", "Bhutan", "Bolivia", "Bosnia and Herzegovina", "Botswana", "Brazil", "Brunei", "Bulgaria", "Burkina Faso", "Burundi", "Cambodia", "Cameroon", "Canada", "Cape Verde", "Cayman Islands", "Central African Republic", "Chad", "Chile", "China", "Colombia", "Comoros", "Congo", "Congo (DRC)", "Costa Rica", "Croatia", "Cuba", "Cyprus", "Czechia", "Denmark", "Djibouti", "Dominica", "Dominican Republic", "Ecuador", "Egypt", "El Salvador", "Equatorial Guinea", "Eritrea", "Estonia", "Eswatini", "Ethiopia", "Fiji", "Finland", "France", "French Guiana", "French Polynesia", "Gabon", "Gambia", "Georgia", "Germany", "Ghana", "Gibraltar", "Greece", "Greenland", "Grenada", "Guadeloupe", "Guam", "Guatemala", "Guinea", "Guinea-Bissau", "Guyana", "Haiti", "Honduras", "Hong Kong", "Hungary", "Iceland", "India", "Indonesia", "Iran", "Iraq", "Ireland", "Israel", "Italy", "Jamaica", "Japan", "Jordan", "Kazakhstan", "Kenya", "Kiribati", "Kuwait", "Kyrgyzstan", "Laos", "Latvia", "Lebanon", "Lesotho", "Liberia", "Libya", "Liechtenstein", "Lithuania", "Luxembourg", "Macau", "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands", "Martinique", "Mauritania", "Mauritius", "Mexico", "Micronesia", "Moldova", "Monaco", "Mongolia", "Montenegro", "Montserrat", "Morocco", "Mozambique", "Myanmar", "Namibia", "Nauru", "Nepal", "Netherlands", "New Caledonia", "New Zealand", "Nicaragua", "Niger", "Nigeria", "Niue", "North Macedonia", "Norway", "Oman", "Pakistan", "Palau", "Palestine", "Panama", "Papua New Guinea", "Paraguay", "Peru", "Philippines", "Poland", "Portugal", "Puerto Rico", "Qatar", "Romania", "Russia", "Rwanda", "Samoa", "San Marino", "Sao Tome and Principe", "Saudi Arabia", "Senegal", "Serbia", "Seychelles", "Sierra Leone", "Singapore", "Slovakia", "Slovenia", "Solomon Islands", "Somalia", "South Africa", "South Korea", "South Sudan", "Spain", "Sri Lanka", "St. Kitts and Nevis", "St. Lucia", "St. Vincent and the Grenadines", "Sudan", "Suriname", "Sweden", "Switzerland", "Syria", "Taiwan", "Tajikistan", "Tanzania", "Thailand", "Timor-Leste", "Togo", "Tonga", "Trinidad and Tobago", "Tunisia", "Turkiye", "Turkmenistan", "Turks and Caicos Islands", "Tuvalu", "Uganda", "Ukraine", "United Arab Emirates", "United Kingdom", "United States", "Uruguay", "Uzbekistan", "Vanuatu", "Vatican City", "Venezuela", "Vietnam", "British Virgin Islands", "U.S. Virgin Islands", "Yemen", "Zambia", "Zimbabwe" ], "type": "string" }, "title": "Countries (multi-select)", "type": "array", "uniqueItems": true }, "country": { "default": "ALL", "description": "Country to search ads in, or ALL for every country. Ignored when the Countries multi-select below is set.", "editor": "select", "enum": [ "ALL", "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BR", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CN", "CO", "KM", "CG", "CD", "CR", "HR", "CU", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FJ", "FI", "FR", "GF", "PF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GN", "GW", "GY", "HT", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IL", "IT", "JM", "JP", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "MK", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PL", "PT", "PR", "QA", "RO", "RU", "RW", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SK", "SI", "SB", "SO", "ZA", "KR", "SS", "ES", "LK", "KN", "LC", "VC", "SD", "SR", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UY", "UZ", "VU", "VA", "VE", "VN", "VG", "VI", "YE", "ZM", "ZW" ], "enumTitles": [ "All Countries", "Afghanistan", "Albania", "Algeria", "American Samoa", "Andorra", "Angola", "Anguilla", "Antarctica", "Antigua and Barbuda", "Argentina", "Armenia", "Aruba", "Australia", "Austria", "Azerbaijan", "Bahamas", "Bahrain", "Bangladesh", "Barbados", "Belarus", "Belgium", "Belize", "Benin", "Bermuda", "Bhutan", "Bolivia", "Bosnia and Herzegovina", "Botswana", "Brazil", "Brunei", "Bulgaria", "Burkina Faso", "Burundi", "Cambodia", "Cameroon", "Canada", "Cape Verde", "Cayman Islands", "Central African Republic", "Chad", "Chile", "China", "Colombia", "Comoros", "Congo", "Congo (DRC)", "Costa Rica", "Croatia", "Cuba", "Cyprus", "Czechia", "Denmark", "Djibouti", "Dominica", "Dominican Republic", "Ecuador", "Egypt", "El Salvador", "Equatorial Guinea", "Eritrea", "Estonia", "Eswatini", "Ethiopia", "Fiji", "Finland", "France", "French Guiana", "French Polynesia", "Gabon", "Gambia", "Georgia", "Germany", "Ghana", "Gibraltar", "Greece", "Greenland", "Grenada", "Guadeloupe", "Guam", "Guatemala", "Guinea", "Guinea-Bissau", "Guyana", "Haiti", "Honduras", "Hong Kong", "Hungary", "Iceland", "India", "Indonesia", "Iran", "Iraq", "Ireland", "Israel", "Italy", "Jamaica", "Japan", "Jordan", "Kazakhstan", "Kenya", "Kiribati", "Kuwait", "Kyrgyzstan", "Laos", "Latvia", "Lebanon", "Lesotho", "Liberia", "Libya", "Liechtenstein", "Lithuania", "Luxembourg", "Macau", "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands", "Martinique", "Mauritania", "Mauritius", "Mexico", "Micronesia", "Moldova", "Monaco", "Mongolia", "Montenegro", "Montserrat", "Morocco", "Mozambique", "Myanmar", "Namibia", "Nauru", "Nepal", "Netherlands", "New Caledonia", "New Zealand", "Nicaragua", "Niger", "Nigeria", "Niue", "North Macedonia", "Norway", "Oman", "Pakistan", "Palau", "Palestine", "Panama", "Papua New Guinea", "Paraguay", "Peru", "Philippines", "Poland", "Portugal", "Puerto Rico", "Qatar", "Romania", "Russia", "Rwanda", "Samoa", "San Marino", "Sao Tome and Principe", "Saudi Arabia", "Senegal", "Serbia", "Seychelles", "Sierra Leone", "Singapore", "Slovakia", "Slovenia", "Solomon Islands", "Somalia", "South Africa", "South Korea", "South Sudan", "Spain", "Sri Lanka", "St. Kitts and Nevis", "St. Lucia", "St. Vincent and the Grenadines", "Sudan", "Suriname", "Sweden", "Switzerland", "Syria", "Taiwan", "Tajikistan", "Tanzania", "Thailand", "Timor-Leste", "Togo", "Tonga", "Trinidad and Tobago", "Tunisia", "Turkiye", "Turkmenistan", "Turks and Caicos Islands", "Tuvalu", "Uganda", "Ukraine", "United Arab Emirates", "United Kingdom", "United States", "Uruguay", "Uzbekistan", "Vanuatu", "Vatican City", "Venezuela", "Vietnam", "British Virgin Islands", "U.S. Virgin Islands", "Yemen", "Zambia", "Zimbabwe" ], "title": "Country", "type": "string" }, "endDate": { "description": "Only include ads that had impressions on or before this date (YYYY-MM-DD).", "editor": "datepicker", "title": "End Date", "type": "string" }, "includeEuDetails": { "default": true, "description": "Fetch per-ad detail data: EU total reach, age/country/gender reach breakdown, targeting, payer/beneficiary, advertiser Instagram profile and page About. Adds one extra request per ad.", "prefill": false, "title": "Include EU Transparency & Advertiser Details", "type": "boolean" }, "maxItems": { "default": 1000, "description": "Stop the whole run after this many ads, across all search targets.", "maximum": 100000, "minimum": 1, "prefill": 3, "title": "Max Ads (global)", "type": "integer" }, "mediaType": { "default": "all", "description": "Filter by the ad's creative media type.", "editor": "select", "enum": [ "all", "image", "video", "meme", "none" ], "enumTitles": [ "All Media", "Image", "Video", "Meme", "No Media" ], "prefill": "all", "title": "Media Type", "type": "string" }, "mode": { "default": "", "description": "What to scrape. Leave empty to process every target list you filled in (searchTerms, pageIds, adIds, bylines) in one run.", "editor": "select", "enum": [ "", "search", "byPage", "byAdId", "byByline" ], "enumTitles": [ "All provided targets (default)", "Search by keyword", "All ads from advertiser Pages", "Lookup specific ads by Ad Library ID", "Search by \"Paid for by\" name" ], "prefill": "search", "title": "Mode", "type": "string" }, "onlyTotal": { "default": false, "description": "Skip ad scraping and return only the total number of results per search target (one lightweight page request, no browser). Counts respect the keyword, country, status, ad type, media type and date window; Facebook caps displayed totals at 50,001 (50,000+). Not available for byline searches.", "prefill": false, "title": "Only Total Results", "type": "boolean" }, "pageIds": { "description": "Facebook Page IDs to fetch all ads from (numeric IDs, or URLs containing view_all_page_id= or profile.php?id=). Each page is searched separately.", "editor": "stringList", "items": { "type": "string" }, "title": "Page IDs / Advertiser Search", "type": "array" }, "publisherPlatforms": { "description": "Only return ads shown on these platforms. Leave empty for all platforms.", "editor": "select", "items": { "enum": [ "FACEBOOK", "INSTAGRAM", "MESSENGER", "AUDIENCE_NETWORK", "WHATSAPP", "THREADS" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "WhatsApp", "Threads" ], "type": "string" }, "title": "Publisher Platforms", "type": "array", "uniqueItems": true }, "rehostMedia": { "default": true, "description": "Copy each ad's primary media into this run's key-value store and output the permanent URL (Facebook's own media URLs expire after a few days). The original signed URL is kept in media_url_original.", "prefill": false, "title": "Rehost Media URLs", "type": "boolean" }, "resultsPerSearch": { "default": 50, "description": "Maximum number of ads to extract per search term / page / ad / byline.", "maximum": 100000, "minimum": 1, "prefill": 3, "title": "Results Per Search Term", "type": "integer" }, "searchTerms": { "description": "Keywords to search for in the Ad Library, one search per term. Example: [\"coffee\", \"nike\"].", "editor": "stringList", "items": { "type": "string" }, "prefill": [ "coffee" ], "title": "Search Terms", "type": "array" }, "searchType": { "default": "keyword_unordered", "description": "How keyword search terms are matched (mode=search only).", "editor": "select", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "enumTitles": [ "Any order (default)", "Exact phrase" ], "prefill": "keyword_unordered", "title": "Keyword Match", "type": "string" }, "sortBy": { "default": "relevance", "description": "Order results by relevance (Facebook's default) or by total impressions.", "editor": "select", "enum": [ "relevance", "total_impressions" ], "enumTitles": [ "Relevance (default)", "Total Impressions" ], "prefill": "relevance", "title": "Sort By", "type": "string" }, "startDate": { "description": "Only include ads that had impressions on or after this date (YYYY-MM-DD). Combined with End Date it forms a delivery window.", "editor": "datepicker", "title": "Start Date", "type": "string" } }, "schemaVersion": 1, "title": "Facebook Ad Transparency Extractor Input", "type": "object" }