Facebook Ad Library Byline & Advertiser Ad Finder

Pull Facebook Ad Library ads by advertiser Page ID, keyword, Ad ID, or "Paid for by" byline, with ad text, media, run dates, creative-reuse counts, and spend or impression ranges for political ads.

Open on Apify GitHub source

Input schema

Input fields, types, required flags, descriptions, defaults, and prefills come from the published definition. Prefill examples are distinct from defaults.

Field	Type	Required	Description
`mode`	string	required	What to scrape. Leave empty to process every target list you filled in (searchTerms, pageIds, adIds, bylines) in one run.
`searchTerms`	array	optional	Keywords to search for in the Ad Library, one search per term. Example: ["coffee", "nike"].
`pageIds`	array	optional	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.

Show all input fields

Field	Type	Required	Description
`mode`	string	required	What to scrape. Leave empty to process every target list you filled in (searchTerms, pageIds, adIds, bylines) in one run.
`searchTerms`	array	optional	Keywords to search for in the Ad Library, one search per term. Example: ["coffee", "nike"].
`pageIds`	array	optional	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.
`adIds`	array	optional	Ad Library IDs to fetch directly (numeric IDs or Ads Library URLs containing ?id=). All other filters are ignored in this mode.
`bylines`	array	optional	Funding-entity / committee names from the "Paid for by" disclaimer on political and issue ads. The actor tries the exact-cased name, retries the original casing, and re-checks each returned ad's byline client-side. Non-EU targets search the political & issue archive; EU/EEA targets use the all-ad-types EU DSA stream (the political archive returns zero there) and may return no byline match because Meta does not always expose it.
`country`	string	optional	Country to search ads in, or ALL for every country. Ignored when the Countries multi-select below is set.
`countries`	array	optional	One or more country codes, searched together as a union (unlike the single Country field). Takes precedence over Country when set.
`adActiveStatus`	string	optional	Filter by ad active status.
`adType`	string	optional	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).
`mediaType`	string	optional	Filter by the ad's creative media type. `meme` is applied server-side only; Meta's payload has no meme marker, so output `media_type` is always image, video or none.
`publisherPlatforms`	array	optional	Only return ads shown on these platforms. Leave empty for all platforms.
`contentLanguages`	array	optional	Only return ads whose creative is written in one of these languages. 2-letter ISO 639-1 codes; leave empty for every language.
`searchType`	string	optional	How keyword search terms are matched (mode=search only).
`startDate`	string	optional	Only include ads that had impressions on or after this date (YYYY-MM-DD). Combined with End Date it forms a delivery window.
`endDate`	string	optional	Only include ads that had impressions on or before this date (YYYY-MM-DD).
`sortBy`	string	optional	Order results by relevance (Facebook's default) or by total impressions.
`resultsPerSearch`	integer	optional	Maximum number of ads to extract per search term / page / ad / byline.
`maxItems`	integer	optional	Stop the whole run after this many ads, across all search targets.
`includeEuDetails`	boolean	optional	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.
`rehostMedia`	boolean	optional	Copy each ad's primary media (up to 15 MB) 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; media_rehost_status records rehosted/disabled/too_large/download_failed/kv_failed. Arrays, carousel cards and Page profile/cover URLs stay signed.
`onlyTotal`	boolean	optional	Skip ad scraping and return one total per search target per country (one lightweight page request per country, 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 or direct ad-ID targets, which get an unsupported_total diagnostic.

Download the published input schema

View complete JSON

{
  "description": "Find Facebook Ad Library ads by advertiser Page, keyword, direct Ad Library ID, or \"Paid for by\" funding name. Returns creative text, media, run dates, platform placements, creative reuse, advertiser context, and political/EU spend, impression and reach data where Meta publishes it. 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": {
      "default": [],
      "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": {
      "default": [],
      "description": "Funding-entity / committee names from the \"Paid for by\" disclaimer on political and issue ads. The actor tries the exact-cased name, retries the original casing, and re-checks each returned ad's byline client-side. Non-EU targets search the political & issue archive; EU/EEA targets use the all-ad-types EU DSA stream (the political archive returns zero there) and may return no byline match because Meta does not always expose it.",
      "editor": "stringList",
      "items": {
        "type": "string"
      },
      "title": "Search by \"Paid for by\" name",
      "type": "array"
    },
    "contentLanguages": {
      "default": [],
      "description": "Only return ads whose creative is written in one of these languages. 2-letter ISO 639-1 codes; leave empty for every language.",
      "editor": "select",
      "items": {
        "enum": [
          "aa",
          "ab",
          "ae",
          "af",
          "ak",
          "am",
          "an",
          "ar",
          "as",
          "av",
          "ay",
          "az",
          "ba",
          "be",
          "bg",
          "bi",
          "bm",
          "bn",
          "bo",
          "br",
          "bs",
          "ca",
          "ce",
          "ch",
          "co",
          "cr",
          "cs",
          "cu",
          "cv",
          "cy",
          "da",
          "de",
          "dv",
          "dz",
          "ee",
          "el",
          "en",
          "eo",
          "es",
          "et",
          "eu",
          "fa",
          "ff",
          "fi",
          "fj",
          "fo",
          "fr",
          "fy",
          "ga",
          "gd",
          "gl",
          "gn",
          "gu",
          "gv",
          "ha",
          "he",
          "hi",
          "ho",
          "hr",
          "ht",
          "hu",
          "hy",
          "hz",
          "ia",
          "id",
          "ie",
          "ig",
          "ii",
          "ik",
          "io",
          "is",
          "it",
          "iu",
          "ja",
          "jv",
          "ka",
          "kg",
          "ki",
          "kj",
          "kk",
          "kl",
          "km",
          "kn",
          "ko",
          "kr",
          "ks",
          "ku",
          "kv",
          "kw",
          "ky",
          "la",
          "lb",
          "lg",
          "li",
          "ln",
          "lo",
          "lt",
          "lu",
          "lv",
          "mg",
          "mh",
          "mi",
          "mk",
          "ml",
          "mn",
          "mr",
          "ms",
          "mt",
          "my",
          "na",
          "nb",
          "nd",
          "ne",
          "ng",
          "nl",
          "nn",
          "no",
          "nr",
          "nv",
          "ny",
          "oc",
          "oj",
          "om",
          "or",
          "os",
          "pa",
          "pi",
          "pl",
          "ps",
          "pt",
          "qu",
          "rm",
          "rn",
          "ro",
          "ru",
          "rw",
          "sa",
          "sc",
          "sd",
          "se",
          "sg",
          "si",
          "sk",
          "sl",
          "sm",
          "sn",
          "so",
          "sq",
          "sr",
          "ss",
          "st",
          "su",
          "sv",
          "sw",
          "ta",
          "te",
          "tg",
          "th",
          "ti",
          "tk",
          "tl",
          "tn",
          "to",
          "tr",
          "ts",
          "tt",
          "tw",
          "ty",
          "ug",
          "uk",
          "ur",
          "uz",
          "ve",
          "vi",
          "vo",
          "wa",
          "wo",
          "xh",
          "yi",
          "yo",
          "za",
          "zh",
          "zu"
        ],
        "enumTitles": [
          "Afar",
          "Abkhazian",
          "Avestan",
          "Afrikaans",
          "Akan",
          "Amharic",
          "Aragonese",
          "Arabic",
          "Assamese",
          "Avaric",
          "Aymara",
          "Azerbaijani",
          "Bashkir",
          "Belarusian",
          "Bulgarian",
          "Bislama",
          "Bambara",
          "Bengali",
          "Tibetan",
          "Breton",
          "Bosnian",
          "Catalan",
          "Chechen",
          "Chamorro",
          "Corsican",
          "Cree",
          "Czech",
          "Church Slavic",
          "Chuvash",
          "Welsh",
          "Danish",
          "German",
          "Divehi",
          "Dzongkha",
          "Ewe",
          "Greek",
          "English",
          "Esperanto",
          "Spanish",
          "Estonian",
          "Basque",
          "Persian",
          "Fulah",
          "Finnish",
          "Fijian",
          "Faroese",
          "French",
          "Western Frisian",
          "Irish",
          "Scottish Gaelic",
          "Galician",
          "Guarani",
          "Gujarati",
          "Manx",
          "Hausa",
          "Hebrew",
          "Hindi",
          "Hiri Motu",
          "Croatian",
          "Haitian Creole",
          "Hungarian",
          "Armenian",
          "Herero",
          "Interlingua",
          "Indonesian",
          "Interlingue",
          "Igbo",
          "Sichuan Yi",
          "Inupiaq",
          "Ido",
          "Icelandic",
          "Italian",
          "Inuktitut",
          "Japanese",
          "Javanese",
          "Georgian",
          "Kongo",
          "Kikuyu",
          "Kuanyama",
          "Kazakh",
          "Kalaallisut",
          "Khmer",
          "Kannada",
          "Korean",
          "Kanuri",
          "Kashmiri",
          "Kurdish",
          "Komi",
          "Cornish",
          "Kyrgyz",
          "Latin",
          "Luxembourgish",
          "Ganda",
          "Limburgish",
          "Lingala",
          "Lao",
          "Lithuanian",
          "Luba-Katanga",
          "Latvian",
          "Malagasy",
          "Marshallese",
          "Maori",
          "Macedonian",
          "Malayalam",
          "Mongolian",
          "Marathi",
          "Malay",
          "Maltese",
          "Burmese",
          "Nauru",
          "Norwegian Bokmal",
          "North Ndebele",
          "Nepali",
          "Ndonga",
          "Dutch",
          "Norwegian Nynorsk",
          "Norwegian",
          "South Ndebele",
          "Navajo",
          "Chichewa",
          "Occitan",
          "Ojibwa",
          "Oromo",
          "Oriya",
          "Ossetian",
          "Punjabi",
          "Pali",
          "Polish",
          "Pashto",
          "Portuguese",
          "Quechua",
          "Romansh",
          "Rundi",
          "Romanian",
          "Russian",
          "Kinyarwanda",
          "Sanskrit",
          "Sardinian",
          "Sindhi",
          "Northern Sami",
          "Sango",
          "Sinhala",
          "Slovak",
          "Slovenian",
          "Samoan",
          "Shona",
          "Somali",
          "Albanian",
          "Serbian",
          "Swati",
          "Southern Sotho",
          "Sundanese",
          "Swedish",
          "Swahili",
          "Tamil",
          "Telugu",
          "Tajik",
          "Thai",
          "Tigrinya",
          "Turkmen",
          "Tagalog",
          "Tswana",
          "Tonga",
          "Turkish",
          "Tsonga",
          "Tatar",
          "Twi",
          "Tahitian",
          "Uyghur",
          "Ukrainian",
          "Urdu",
          "Uzbek",
          "Venda",
          "Vietnamese",
          "Volapuk",
          "Walloon",
          "Wolof",
          "Xhosa",
          "Yiddish",
          "Yoruba",
          "Zhuang",
          "Chinese",
          "Zulu"
        ],
        "type": "string"
      },
      "title": "Ad Content Languages",
      "type": "array",
      "uniqueItems": true
    },
    "countries": {
      "default": [],
      "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. `meme` is applied server-side only; Meta's payload has no meme marker, so output `media_type` is always image, video or none.",
      "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 one total per search target per country (one lightweight page request per country, 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 or direct ad-ID targets, which get an unsupported_total diagnostic.",
      "prefill": false,
      "title": "Only Total Results",
      "type": "boolean"
    },
    "pageIds": {
      "default": [],
      "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": {
      "default": [],
      "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 (up to 15 MB) 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; media_rehost_status records rehosted/disabled/too_large/download_failed/kv_failed. Arrays, carousel cards and Page profile/cover URLs stay signed.",
      "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": {
      "default": [],
      "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"
    }
  },
  "required": [
    "mode"
  ],
  "schemaVersion": 1,
  "title": "Facebook Ad Library Byline & Advertiser Ad Finder Input",
  "type": "object"
}

Output schema

Published result links and storage locations. This schema is not an exhaustive contract for every field in a dataset record.

Field	Type	Required	Description
`ads`	string	optional	Dataset containing all scraped Facebook ads, one JSON object per ad

Download the published output schema

View complete JSON

{
  "actorOutputSchemaVersion": 1,
  "description": "One record per Facebook Ad Library ad: creative text, media, run dates, platform placements, creative reuse, advertiser context, and political/EU spend, impression and reach data where Meta publishes it. Fields the source does not provide for an ad are omitted.",
  "properties": {
    "ads": {
      "description": "Dataset containing all scraped Facebook ads, one JSON object per ad",
      "template": "{{links.apiDefaultDatasetUrl}}/items",
      "title": "Ad Library Data",
      "type": "string"
    }
  },
  "title": "Facebook Ad Library Byline & Advertiser Ad Finder Output"
}

Dataset schema

Published dataset views and any declared field definitions. A view can select only a subset of the returned record fields.

Download the published dataset schema

View complete JSON

{
  "actorSpecification": 1,
  "title": "Facebook Ad Library Data",
  "views": {
    "detailed": {
      "display": {
        "component": "table",
        "properties": {
          "ad_id": {
            "format": "text",
            "label": "Ad ID"
          },
          "ad_snapshot_url": {
            "format": "link",
            "label": "Snapshot URL"
          },
          "ad_text": {
            "format": "text",
            "label": "Ad Text"
          },
          "advertiser_ig_followers": {
            "format": "text",
            "label": "IG Followers"
          },
          "advertiser_ig_username": {
            "format": "text",
            "label": "IG Username"
          },
          "byline": {
            "format": "text",
            "label": "Paid For By"
          },
          "caption": {
            "format": "text",
            "label": "Caption"
          },
          "collation_count": {
            "format": "text",
            "label": "Creative Reuse"
          },
          "collation_id": {
            "format": "text",
            "label": "Collation ID"
          },
          "contains_digital_created_media": {
            "format": "text",
            "label": "AI Media"
          },
          "cta_text": {
            "format": "text",
            "label": "CTA"
          },
          "currency": {
            "format": "text",
            "label": "Currency"
          },
          "days_running": {
            "format": "text",
            "label": "Days Running"
          },
          "disclaimer_label": {
            "format": "text",
            "label": "Disclaimer"
          },
          "display_format": {
            "format": "text",
            "label": "Display Format"
          },
          "end_date": {
            "format": "text",
            "label": "Ended"
          },
          "gated_type": {
            "format": "text",
            "label": "Gated Type"
          },
          "image_urls": {
            "format": "text",
            "label": "Image URLs"
          },
          "impressions": {
            "format": "text",
            "label": "Impressions"
          },
          "is_active": {
            "format": "text",
            "label": "Active"
          },
          "link_description": {
            "format": "text",
            "label": "Link Description"
          },
          "link_url": {
            "format": "link",
            "label": "Link URL"
          },
          "media_type": {
            "format": "text",
            "label": "Media Type"
          },
          "media_url": {
            "format": "link",
            "label": "Media URL"
          },
          "page_categories": {
            "format": "text",
            "label": "Page Categories"
          },
          "page_id": {
            "format": "text",
            "label": "Page ID"
          },
          "page_like_count": {
            "format": "text",
            "label": "Page Likes"
          },
          "page_name": {
            "format": "text",
            "label": "Page Name"
          },
          "page_url": {
            "format": "link",
            "label": "Page URL"
          },
          "publisher_platform": {
            "format": "text",
            "label": "Platforms"
          },
          "reach_estimate": {
            "format": "text",
            "label": "Reach Estimate"
          },
          "regional_regulation_data": {
            "format": "text",
            "label": "Regional Regulation"
          },
          "resolved_ad_text": {
            "format": "text",
            "label": "Resolved Ad Text"
          },
          "scraped_at": {
            "format": "text",
            "label": "Scraped At"
          },
          "search_term": {
            "format": "text",
            "label": "Search Term"
          },
          "spend": {
            "format": "text",
            "label": "Spend"
          },
          "start_date": {
            "format": "text",
            "label": "Started"
          },
          "status": {
            "format": "text",
            "label": "Status"
          },
          "template_tokens": {
            "format": "text",
            "label": "Template Tokens"
          },
          "title": {
            "format": "text",
            "label": "Title"
          },
          "video_urls": {
            "format": "text",
            "label": "Video URLs"
          }
        }
      },
      "title": "Detailed View",
      "transformation": {
        "fields": [
          "ad_id",
          "page_name",
          "page_id",
          "page_url",
          "ad_text",
          "resolved_ad_text",
          "template_tokens",
          "title",
          "caption",
          "cta_text",
          "link_url",
          "link_description",
          "display_format",
          "start_date",
          "end_date",
          "days_running",
          "status",
          "is_active",
          "media_type",
          "media_url",
          "image_urls",
          "video_urls",
          "publisher_platform",
          "collation_count",
          "collation_id",
          "page_like_count",
          "page_categories",
          "advertiser_ig_username",
          "advertiser_ig_followers",
          "spend",
          "impressions",
          "reach_estimate",
          "currency",
          "byline",
          "disclaimer_label",
          "gated_type",
          "regional_regulation_data",
          "contains_digital_created_media",
          "ad_snapshot_url",
          "search_term",
          "scraped_at"
        ]
      }
    },
    "euTransparency": {
      "display": {
        "component": "table",
        "properties": {
          "ad_id": {
            "format": "text",
            "label": "Ad ID"
          },
          "ad_snapshot_url": {
            "format": "link",
            "label": "Snapshot URL"
          },
          "age_country_gender_reach_breakdown": {
            "format": "text",
            "label": "Reach Breakdown"
          },
          "audience_age_gender": {
            "format": "text",
            "label": "Audience Age/Gender"
          },
          "audience_location": {
            "format": "text",
            "label": "Audience Location"
          },
          "audience_single_country": {
            "format": "text",
            "label": "Country"
          },
          "byline": {
            "format": "text",
            "label": "Paid For By"
          },
          "categories": {
            "format": "text",
            "label": "Categories"
          },
          "currency": {
            "format": "text",
            "label": "Currency"
          },
          "eu_total_reach": {
            "format": "text",
            "label": "EU Reach"
          },
          "impressions": {
            "format": "text",
            "label": "Impressions"
          },
          "is_violating_eu_siep": {
            "format": "text",
            "label": "EU SIEP Violation"
          },
          "page_name": {
            "format": "text",
            "label": "Page Name"
          },
          "payer_beneficiary": {
            "format": "text",
            "label": "Payer / Beneficiary"
          },
          "reach_estimate": {
            "format": "text",
            "label": "Reach"
          },
          "search_term": {
            "format": "text",
            "label": "Search Term"
          },
          "spend": {
            "format": "text",
            "label": "Spend"
          },
          "spend_lower_bound": {
            "format": "text",
            "label": "Spend Min"
          },
          "spend_upper_bound": {
            "format": "text",
            "label": "Spend Max"
          },
          "target_age_audience": {
            "format": "text",
            "label": "Target Ages"
          },
          "target_gender_audience": {
            "format": "text",
            "label": "Target Gender"
          },
          "target_location_audience": {
            "format": "text",
            "label": "Target Locations"
          },
          "violation_types": {
            "format": "text",
            "label": "Violations"
          }
        }
      },
      "title": "EU Transparency & Political Ads",
      "transformation": {
        "fields": [
          "ad_id",
          "page_name",
          "byline",
          "categories",
          "spend",
          "spend_lower_bound",
          "spend_upper_bound",
          "impressions",
          "reach_estimate",
          "currency",
          "eu_total_reach",
          "target_age_audience",
          "target_gender_audience",
          "target_location_audience",
          "age_country_gender_reach_breakdown",
          "payer_beneficiary",
          "audience_age_gender",
          "audience_location",
          "audience_single_country",
          "violation_types",
          "is_violating_eu_siep",
          "ad_snapshot_url",
          "search_term"
        ]
      }
    },
    "overview": {
      "display": {
        "component": "table",
        "properties": {
          "ad_id": {
            "format": "text",
            "label": "Ad ID"
          },
          "ad_snapshot_url": {
            "format": "link",
            "label": "Snapshot URL"
          },
          "ad_text": {
            "format": "text",
            "label": "Ad Text"
          },
          "collation_count": {
            "format": "text",
            "label": "Creative Reuse"
          },
          "cta_text": {
            "format": "text",
            "label": "CTA"
          },
          "impressions": {
            "format": "text",
            "label": "Impressions"
          },
          "link_url": {
            "format": "link",
            "label": "Link URL"
          },
          "media_type": {
            "format": "text",
            "label": "Media"
          },
          "page_name": {
            "format": "text",
            "label": "Page Name"
          },
          "publisher_platform": {
            "format": "text",
            "label": "Platforms"
          },
          "search_term": {
            "format": "text",
            "label": "Search Term"
          },
          "spend": {
            "format": "text",
            "label": "Spend"
          },
          "start_date": {
            "format": "text",
            "label": "Started"
          },
          "status": {
            "format": "text",
            "label": "Status"
          }
        }
      },
      "title": "Ad Overview",
      "transformation": {
        "fields": [
          "ad_id",
          "page_name",
          "ad_text",
          "start_date",
          "status",
          "media_type",
          "cta_text",
          "link_url",
          "publisher_platform",
          "collation_count",
          "spend",
          "impressions",
          "ad_snapshot_url",
          "search_term"
        ]
      }
    }
  }
}

Key-value schema

Published key-value store definitions, when provided by this build.

This definition is not present in the default published build. See the published README for available documentation.

Published README

Read the full published documentation

Facebook Ad Library Byline & Advertiser Ad Finder

Look up who is advertising and what they are running. This actor reads Meta's public Facebook Ad Library without a login, a cookie, or a Meta API token. Start from an advertiser Page, a specific Ad Library ID, a free-text keyword, or the "Paid for by" name printed on a political disclaimer, and get one clean record per ad with its creative, media, run window, placements, creative-reuse count, advertiser context, and - when Meta publishes them for political or EU-regulated ads - spend, impressions and reach.

What this actor does

Four lookup paths in one run: keyword search, advertiser Page (numeric ID or URL), direct Ad Library ID, and "Paid for by" byline. Fill in one list or several; a single run processes them all.
Real request-side filters: country (single or multi-country union), content language, active/inactive status, ad category, media type, publisher platform, keyword match mode, delivery-date window and sort order.
Creative in full: ad body, title, caption, description, call-to-action, destination link, single image/video URLs, video previews, carousel cards and dynamic-creative placeholder tokens.
Advertiser context: Page name and ID, Page likes, categories, profile picture and page URL, plus optional per-ad detail data such as page About text, Instagram handle and followers.
Political and EU transparency: spend and impression ranges, byline, disclaimer label, payer/beneficiary, EU total reach, age/gender/location targeting and reach breakdowns.
Honest by design: spend, impressions and reach appear only where Meta actually discloses them. Commercial ads never get a guessed number; the field is simply absent. Every empty field is dropped from the record.
Cookieless and setup-free: no cookies, no login, no API key, and no proxy configuration. The actor manages its own connection automatically.

Output per ad

Every record carries ad_id (Ad Library archive ID), ad_snapshot_url and sourceUrl (the ad's public permalink), recordType: "ad", scraped_at and scrapedAt.

Identity and advertiser

page_id, page_name, page_url, page_profile_uri, page_profile_picture_url
page_like_count, page_categories, page_is_deleted, page_is_restricted, page_verification, page_alias, page_cover_photo_url
advertiser_about, advertiser_page_category, advertiser_ig_username, advertiser_ig_followers, advertiser_ig_verified, entity_type, page_spend

Creative

ad_text, title, caption, link_description, cta_text, cta_type, display_format
link_url - the destination the ad sends clicks to
media_type - image, video or none (derived from the creative). The mediaType=meme input is a server-side filter; Meta's payload has no meme marker, so the output never invents meme.
media_url - primary creative. With rehostMedia, a successful copy is in media_url, the signed original in media_url_original/media_url_original_expires_at, and media_rehost_status says rehosted; media_url_expires_at is present only while media_url itself is a signed fbcdn URL (rehost off/failed). Failure values are disabled, too_large, download_failed and kv_failed, with media_rehost_reason.
image_urls[], video_urls[], video_preview_urls[]
cards[] - carousel cards with title, body, caption, linkUrl, ctaText, ctaType, imageUrl, videoUrls, videoPreviewUrl
template_tokens[], template_body, template_title, resolved_ad_text, resolved_title - dynamic-creative (DCO/DPA) placeholders and any token-free card variant

Delivery

start_date, end_date - YYYY-MM-DD
days_running - days between start and end (or today for active ads)
status - active or inactive; omitted together with is_active when Meta does not send a boolean (no unknown sentinel)
publisher_platform[] - e.g. FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK
collation_count, collation_id - Meta's creative-reuse group and count
categories[], gated_type, is_aaa_eligible, contains_digital_created_media, contains_sensitive_content, has_user_reported, hide_data_status, regional_regulation_data

Political and EU transparency (only when Meta publishes it)

spend, spend_lower_bound, spend_upper_bound, currency
impressions, impressions_index, impressions_lower_bound, impressions_upper_bound
reach_estimate, reach_lower_bound, reach_upper_bound
byline, disclaimer_label
eu_total_reach, uk_total_reach, br_total_reach
target_age_audience, target_gender_audience, target_location_audience
age_country_gender_reach_breakdown, audience_age_gender, audience_location, audience_single_country
payer_beneficiary[], violation_types[], is_violating_eu_siep

When onlyTotal is on, the dataset contains one summary record per target per country instead: type: "facebook_ads_library_total", recordType: "total", search_term, country, total_results, scraped_at. Totals are not available for byline or direct ad-ID targets because the Ad Library page has no byline filter and an ad page has no search result list; those targets get an unsupported_total diagnostic.

Input

Field	Type	Default	Description
`mode`	string	`""`	`""` processes every provided target list; or choose `search`, `byPage`, `byAdId`, `byByline`
`searchTerms`	array	`[]`	Keywords to search, one query per term. Prefill: `["coffee"]`
`pageIds`	array	`[]`	Facebook Page IDs, or URLs containing `view_all_page_id=` / `profile.php?id=`
`adIds`	array	`[]`	Ad Library IDs, or ads-library URLs containing `?id=`
`bylines`	array	`[]`	Funding-entity names from a political ad's "Paid for by" disclaimer. Non-EU targets use the political archive; EU/EEA targets use the all-types EU DSA stream and a client-side byline check
`country`	string	`ALL`	Single ISO 3166-1 alpha-2 country, or `ALL`
`countries`	array	`[]`	Multiple country codes, searched as a union. Takes precedence over `country`
`adActiveStatus`	string	`active`	`all`, `active` or `inactive`
`adType`	string	`all`	`all`, `political_and_issue_ads`, `housing`, `employment` or `credit`
`mediaType`	string	`all`	`all`, `image`, `video`, `meme` or `none`. `meme` is a server-side filter only; output `media_type` stays `image`/`video`/`none`
`publisherPlatforms`	array	`[]`	Only ads shown on Facebook, Instagram, Messenger, Audience Network, WhatsApp or Threads
`contentLanguages`	array	`[]`	2-letter ISO 639-1 creative languages (full list in the dropdown)
`searchType`	string	`keyword_unordered`	`keyword_unordered` or `keyword_exact_phrase`
`startDate`	string	-	Include ads with delivery on or after this date (`YYYY-MM-DD`)
`endDate`	string	-	Include ads with delivery on or before this date (`YYYY-MM-DD`)
`sortBy`	string	`relevance`	`relevance` or `total_impressions`
`resultsPerSearch`	integer	`50`	Cap per target (1-100000). Prefill: `3`
`maxItems`	integer	`1000`	Cap for the whole run across all targets (1-100000). Prefill: `3`
`includeEuDetails`	boolean	`true`	Fetch per-ad EU transparency and advertiser-profile detail. Adds one request per ad. Prefill: `false`
`rehostMedia`	boolean	`true`	Copy the primary media (max 15 MB) into the run's key-value store and emit a permanent URL. `media_rehost_status` records success/failure; arrays, carousel cards and Page profile/cover URLs stay signed. Prefill: `false`
`onlyTotal`	boolean	`false`	Skip ad records and return one result count per target per country. Not available for byline or direct ad-ID targets

Provide at least one of searchTerms, pageIds, adIds or bylines. Per-mode requirements are checked in code, so an empty list simply produces a clear status message instead of a crash.

Example: every active ad from an advertiser Page

{
  "mode": "byPage",
  "pageIds": ["15087023444"],
  "countries": ["US", "CA"],
  "adActiveStatus": "active",
  "maxItems": 200
}

Example: trace a political funding entity

{
  "mode": "byByline",
  "bylines": ["JON OSSOFF FOR SENATE"],
  "countries": ["US"],
  "adType": "political_and_issue_ads",
  "maxItems": 50
}

Example: exact-phrase creative search with a delivery window

{
  "mode": "search",
  "searchTerms": ["free shipping"],
  "searchType": "keyword_exact_phrase",
  "country": "GB",
  "startDate": "2026-01-01",
  "endDate": "2026-06-30",
  "mediaType": "video",
  "sortBy": "total_impressions"
}

Example: fetch known ads by ID, with EU detail

{
  "mode": "byAdId",
  "adIds": ["1098840072544828", "2619351891814847"],
  "includeEuDetails": true,
  "rehostMedia": true,
  "maxItems": 2
}

Example: count results without downloading them

{
  "mode": "search",
  "searchTerms": ["nike", "adidas"],
  "country": "US",
  "onlyTotal": true
}

Use cases

Competitive ad monitoring: pull the current rotation for a competitor Page and compare hooks, offers and landing pages.
Creative research: collect live ad copy, images, video and carousel cards for a swipe file or mood board.
Political and issue-ad accountability: follow a "Paid for by" committee, then read its spend, impressions and payer/beneficiary data.
EU DSA transparency: audit an advertiser's EU reach, targeting and demographic breakdown.
Creative-reuse analysis: sort by collation_count to see which creative a brand is scaling hardest.
Known-ad due diligence: resolve a specific Ad Library ID to its full record before it disappears from the live library.

FAQ

Do I need a Facebook account, cookies or a developer app? No. The actor reads the public Ad Library anonymously. There are no cookie, login or API-key inputs, and none are needed for the daily test.

Why are spend and impressions missing on some ads? Meta only publishes those figures for political/issue ads and some EU/UK transparency ads. The actor never estimates or fills them for ordinary commercial ads; the fields are omitted instead.

Why is a media URL missing or different? Facebook's own media URLs are signed and expire after a few days. With rehostMedia on, the actor copies the primary media (up to 15 MB) to the run's key-value store and returns a permanent URL in media_url, keeping the original in media_url_original and its expiry in media_url_original_expires_at. media_rehost_status tells you whether the copy succeeded; if it is too_large, download_failed or kv_failed, media_url remains the signed original. Per-card, array and Page profile/cover URLs stay as Meta served them.

How many ads can one run return? The Ad Library serves 10 ads per page and the actor follows the cursor until it reaches maxItems or the server runs out. Meta's displayed totals cap at 50,001, so a search may honestly report "50,000+" rather than an exact larger number.

Why did a byline search return nothing? Meta's byline filter matches the funding-entity string exactly and only works inside the political archive. The actor tries the uppercase form first, then the original casing, and also re-checks each returned ad's byline field client-side. If nothing matches, you get a diagnostic rather than an unrelated ad.

Why did an EU political or byline search get remapped? The political-and-issue archive excludes EU/EEA countries. When those filters are combined, the actor searches the EU transparency stream (adType=all) and warns in the run status. For byline targets in EU/EEA countries, the match is checked client-side because Meta may not expose the funding byline there; a zero result is explained as an EU archive limitation, not proof that the funder has no ads. Filter on categories to pick out political ads.

What is collation_count? Meta's own count of ad variants that share one creative and text. It is the fastest built-in signal for creative reuse.

Can one run mix keyword, Page, Ad ID and byline lookups? Yes. Leave mode empty and fill in any combination of the four lists. Each target is processed in order and every ad is deduplicated by ad_id across the whole run.

Does the actor need a proxy? No. It chooses a working connection automatically; there is nothing to configure.

Is this affiliated with Meta? No. It is an independent tool reading the same public Ad Library pages anyone can browse at facebook.com/ads/library.

Limitations

Meta's public payload does not expose spend, impressions or reach for ordinary commercial ads. Those fields are omitted, never estimated.
Media URLs from Facebook's CDN are signed and expire. With rehostMedia, only the primary media_url is copied (15 MB cap); image_urls, video_urls, video_preview_urls, carousel-card URLs and Page profile/cover URLs remain signed. A failed/oversized rehost is marked in media_rehost_status and keeps the signed URL rather than pretending to be permanent.
The Ad Library page size is 10. Large runs are cursor-bound and can be slow.
Displayed totals cap at 50,001 ("50,000+"). The actor reports what Meta reports. onlyTotal queries one country per record; it does not add the countries together.
Byline filtering is exact-cased and works only inside the political/issue archive. Lowercase retries and a client-side byline check are applied. In EU/EEA countries the actor searches adType=all because the political archive returns zero there; Meta may not expose the funding byline, so an EU byline zero is a documented limitation, not proof of no ads.
Dynamic-creative (DCO/DPA) templates sometimes contain placeholders whose values are not in the public payload. The actor keeps the placeholder and attaches a token-free card variant when one exists; it never invents a brand.
mediaType=meme is a server-side filter only. The payload has no meme marker, so output media_type is always image, video or none.
status/is_active are omitted when Meta does not send a boolean; no unknown sentinel is emitted.
Page-name typeahead is not supported: use a numeric Page ID or a Page URL containing the ID.
Page-owner contact details and admin history are not part of the ad payload and are not shipped.
Byline and direct ad-ID totals are unavailable; onlyTotal emits an unsupported_total diagnostic for those targets because the Ad Library page has no byline filter and an ad page has no search result list.
Facebook Page URLs (ad_snapshot_url, page_url, page_profile_uri) return 403 to non-browser HTTP clients. They open normally in a browser; this is an anti-bot posture, not a broken URL.
Scheduled watchlists, diffs and e-commerce enrichment are separate use cases and are not part of this actor.

Python quickstart

Use a schema-derived input and the Python standard library to start a run. An Apify account and token are required for execution.

Open the step-by-step Python guide →

Source build m9SEVLoISWJhDLniO. Documentation is regenerated from the default published build; private drafts are not included.