{
"openapi": "3.0.1",
"info": {
"title": "Facebook Ads Library Scraper & Ad Monitor",
"description": "Scrape the Meta Ad Library by keyword, Facebook Page or Ad Library URL: ad copy, media, start dates, days running, platforms, landing pages, EU reach and political spend. For competitor research, ad spying and brand monitoring, with only-new-ads alerts. No login, no browser.",
"version": "1.0",
"x-build-id": "huzd7pNgPW0kLaDi6"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/panix~facebook-ads-library-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-panix-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/panix~facebook-ads-library-scraper/runs": {
"post": {
"operationId": "runs-sync-panix-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/panix~facebook-ads-library-scraper/run-sync": {
"post": {
"operationId": "run-sync-panix-facebook-ads-library-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"properties": {
"searchTerms": {
"title": "Search terms (keywords or brand names)",
"type": "array",
"description": "Words to search in the Meta Ad Library, for example running shoes or shopify. Each term is a separate search.",
"items": {
"type": "string"
}
},
"pageUrls": {
"title": "Facebook Pages (advertisers)",
"type": "array",
"description": "Every ad of these advertisers. Paste a Page URL (https://www.facebook.com/nike), a numeric Page ID (15087023444) or an Ad Library page link (...view_all_page_id=...).",
"items": {
"type": "string"
}
},
"startUrls": {
"title": "Ad Library URLs",
"type": "array",
"description": "URLs copied from facebook.com/ads/library: a search, an advertiser view or a single ad (?id=...). Every filter in the URL is kept (country, status, ad type, media, platforms, languages, dates, sort, exact phrase).",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"title": "URL of a web page",
"format": "uri"
}
}
}
},
"countries": {
"title": "Countries",
"type": "array",
"description": "Where the ads were shown. Choose several to search each country separately, or All countries.",
"items": {
"type": "string",
"enum": [
"ALL",
"AD",
"AE",
"AF",
"AG",
"AI",
"AL",
"AM",
"AO",
"AQ",
"AR",
"AS",
"AT",
"AU",
"AW",
"AX",
"AZ",
"BA",
"BB",
"BD",
"BE",
"BF",
"BG",
"BH",
"BI",
"BJ",
"BL",
"BM",
"BN",
"BO",
"BQ",
"BR",
"BS",
"BT",
"BV",
"BW",
"BY",
"BZ",
"CA",
"CC",
"CD",
"CF",
"CG",
"CH",
"CI",
"CK",
"CL",
"CM",
"CN",
"CO",
"CR",
"CU",
"CV",
"CW",
"CX",
"CY",
"CZ",
"DE",
"DJ",
"DK",
"DM",
"DO",
"DZ",
"EC",
"EE",
"EG",
"EH",
"ER",
"ES",
"ET",
"FI",
"FJ",
"FK",
"FM",
"FO",
"FR",
"GA",
"GB",
"GD",
"GE",
"GF",
"GG",
"GH",
"GI",
"GL",
"GM",
"GN",
"GP",
"GQ",
"GR",
"GS",
"GT",
"GU",
"GW",
"GY",
"HK",
"HM",
"HN",
"HR",
"HT",
"HU",
"ID",
"IE",
"IL",
"IM",
"IN",
"IO",
"IQ",
"IR",
"IS",
"IT",
"JE",
"JM",
"JO",
"JP",
"KE",
"KG",
"KH",
"KI",
"KM",
"KN",
"KP",
"KR",
"KW",
"KY",
"KZ",
"LA",
"LB",
"LC",
"LI",
"LK",
"LR",
"LS",
"LT",
"LU",
"LV",
"LY",
"MA",
"MC",
"MD",
"ME",
"MF",
"MG",
"MH",
"MK",
"ML",
"MM",
"MN",
"MO",
"MP",
"MQ",
"MR",
"MS",
"MT",
"MU",
"MV",
"MW",
"MX",
"MY",
"MZ",
"NA",
"NC",
"NE",
"NF",
"NG",
"NI",
"NL",
"NO",
"NP",
"NR",
"NU",
"NZ",
"OM",
"PA",
"PE",
"PF",
"PG",
"PH",
"PK",
"PL",
"PM",
"PN",
"PR",
"PS",
"PT",
"PW",
"PY",
"QA",
"RE",
"RO",
"RS",
"RU",
"RW",
"SA",
"SB",
"SC",
"SD",
"SE",
"SG",
"SH",
"SI",
"SJ",
"SK",
"SL",
"SM",
"SN",
"SO",
"SR",
"SS",
"ST",
"SV",
"SX",
"SY",
"SZ",
"TC",
"TD",
"TF",
"TG",
"TH",
"TJ",
"TK",
"TL",
"TM",
"TN",
"TO",
"TR",
"TT",
"TV",
"TW",
"TZ",
"UA",
"UG",
"UM",
"US",
"UY",
"UZ",
"VA",
"VC",
"VE",
"VG",
"VI",
"VN",
"VU",
"WF",
"WS",
"XK",
"YE",
"YT",
"ZA",
"ZM",
"ZW"
],
"enumTitles": [
"All countries",
"Andorra (AD)",
"United Arab Emirates (AE)",
"Afghanistan (AF)",
"Antigua and Barbuda (AG)",
"Anguilla (AI)",
"Albania (AL)",
"Armenia (AM)",
"Angola (AO)",
"Antarctica (AQ)",
"Argentina (AR)",
"American Samoa (AS)",
"Austria (AT)",
"Australia (AU)",
"Aruba (AW)",
"Aland Islands (AX)",
"Azerbaijan (AZ)",
"Bosnia and Herzegovina (BA)",
"Barbados (BB)",
"Bangladesh (BD)",
"Belgium (BE)",
"Burkina Faso (BF)",
"Bulgaria (BG)",
"Bahrain (BH)",
"Burundi (BI)",
"Benin (BJ)",
"Saint Barthelemy (BL)",
"Bermuda (BM)",
"Brunei (BN)",
"Bolivia (BO)",
"Caribbean Netherlands (BQ)",
"Brazil (BR)",
"Bahamas (BS)",
"Bhutan (BT)",
"Bouvet Island (BV)",
"Botswana (BW)",
"Belarus (BY)",
"Belize (BZ)",
"Canada (CA)",
"Cocos (Keeling) Islands (CC)",
"Congo (DRC) (CD)",
"Central African Republic (CF)",
"Congo (Republic) (CG)",
"Switzerland (CH)",
"Cote d'Ivoire (CI)",
"Cook Islands (CK)",
"Chile (CL)",
"Cameroon (CM)",
"China (CN)",
"Colombia (CO)",
"Costa Rica (CR)",
"Cuba (CU)",
"Cape Verde (CV)",
"Curacao (CW)",
"Christmas Island (CX)",
"Cyprus (CY)",
"Czech Republic (CZ)",
"Germany (DE)",
"Djibouti (DJ)",
"Denmark (DK)",
"Dominica (DM)",
"Dominican Republic (DO)",
"Algeria (DZ)",
"Ecuador (EC)",
"Estonia (EE)",
"Egypt (EG)",
"Western Sahara (EH)",
"Eritrea (ER)",
"Spain (ES)",
"Ethiopia (ET)",
"Finland (FI)",
"Fiji (FJ)",
"Falkland Islands (FK)",
"Micronesia (FM)",
"Faroe Islands (FO)",
"France (FR)",
"Gabon (GA)",
"United Kingdom (GB)",
"Grenada (GD)",
"Georgia (GE)",
"French Guiana (GF)",
"Guernsey (GG)",
"Ghana (GH)",
"Gibraltar (GI)",
"Greenland (GL)",
"Gambia (GM)",
"Guinea (GN)",
"Guadeloupe (GP)",
"Equatorial Guinea (GQ)",
"Greece (GR)",
"South Georgia and the South Sandwich Islands (GS)",
"Guatemala (GT)",
"Guam (GU)",
"Guinea-Bissau (GW)",
"Guyana (GY)",
"Hong Kong (HK)",
"Heard Island and McDonald Islands (HM)",
"Honduras (HN)",
"Croatia (HR)",
"Haiti (HT)",
"Hungary (HU)",
"Indonesia (ID)",
"Ireland (IE)",
"Israel (IL)",
"Isle of Man (IM)",
"India (IN)",
"British Indian Ocean Territory (IO)",
"Iraq (IQ)",
"Iran (IR)",
"Iceland (IS)",
"Italy (IT)",
"Jersey (JE)",
"Jamaica (JM)",
"Jordan (JO)",
"Japan (JP)",
"Kenya (KE)",
"Kyrgyzstan (KG)",
"Cambodia (KH)",
"Kiribati (KI)",
"Comoros (KM)",
"Saint Kitts and Nevis (KN)",
"North Korea (KP)",
"South Korea (KR)",
"Kuwait (KW)",
"Cayman Islands (KY)",
"Kazakhstan (KZ)",
"Laos (LA)",
"Lebanon (LB)",
"Saint Lucia (LC)",
"Liechtenstein (LI)",
"Sri Lanka (LK)",
"Liberia (LR)",
"Lesotho (LS)",
"Lithuania (LT)",
"Luxembourg (LU)",
"Latvia (LV)",
"Libya (LY)",
"Morocco (MA)",
"Monaco (MC)",
"Moldova (MD)",
"Montenegro (ME)",
"Saint Martin (MF)",
"Madagascar (MG)",
"Marshall Islands (MH)",
"North Macedonia (MK)",
"Mali (ML)",
"Myanmar (MM)",
"Mongolia (MN)",
"Macau (MO)",
"Northern Mariana Islands (MP)",
"Martinique (MQ)",
"Mauritania (MR)",
"Montserrat (MS)",
"Malta (MT)",
"Mauritius (MU)",
"Maldives (MV)",
"Malawi (MW)",
"Mexico (MX)",
"Malaysia (MY)",
"Mozambique (MZ)",
"Namibia (NA)",
"New Caledonia (NC)",
"Niger (NE)",
"Norfolk Island (NF)",
"Nigeria (NG)",
"Nicaragua (NI)",
"Netherlands (NL)",
"Norway (NO)",
"Nepal (NP)",
"Nauru (NR)",
"Niue (NU)",
"New Zealand (NZ)",
"Oman (OM)",
"Panama (PA)",
"Peru (PE)",
"French Polynesia (PF)",
"Papua New Guinea (PG)",
"Philippines (PH)",
"Pakistan (PK)",
"Poland (PL)",
"Saint Pierre and Miquelon (PM)",
"Pitcairn Islands (PN)",
"Puerto Rico (PR)",
"Palestine (PS)",
"Portugal (PT)",
"Palau (PW)",
"Paraguay (PY)",
"Qatar (QA)",
"Reunion (RE)",
"Romania (RO)",
"Serbia (RS)",
"Russia (RU)",
"Rwanda (RW)",
"Saudi Arabia (SA)",
"Solomon Islands (SB)",
"Seychelles (SC)",
"Sudan (SD)",
"Sweden (SE)",
"Singapore (SG)",
"Saint Helena (SH)",
"Slovenia (SI)",
"Svalbard and Jan Mayen (SJ)",
"Slovakia (SK)",
"Sierra Leone (SL)",
"San Marino (SM)",
"Senegal (SN)",
"Somalia (SO)",
"Suriname (SR)",
"South Sudan (SS)",
"Sao Tome and Principe (ST)",
"El Salvador (SV)",
"Sint Maarten (SX)",
"Syria (SY)",
"Eswatini (SZ)",
"Turks and Caicos Islands (TC)",
"Chad (TD)",
"French Southern Territories (TF)",
"Togo (TG)",
"Thailand (TH)",
"Tajikistan (TJ)",
"Tokelau (TK)",
"Timor-Leste (TL)",
"Turkmenistan (TM)",
"Tunisia (TN)",
"Tonga (TO)",
"Turkey (TR)",
"Trinidad and Tobago (TT)",
"Tuvalu (TV)",
"Taiwan (TW)",
"Tanzania (TZ)",
"Ukraine (UA)",
"Uganda (UG)",
"U.S. Minor Outlying Islands (UM)",
"United States (US)",
"Uruguay (UY)",
"Uzbekistan (UZ)",
"Vatican City (VA)",
"Saint Vincent and the Grenadines (VC)",
"Venezuela (VE)",
"British Virgin Islands (VG)",
"U.S. Virgin Islands (VI)",
"Vietnam (VN)",
"Vanuatu (VU)",
"Wallis and Futuna (WF)",
"Samoa (WS)",
"Kosovo (XK)",
"Yemen (YE)",
"Mayotte (YT)",
"South Africa (ZA)",
"Zambia (ZM)",
"Zimbabwe (ZW)"
]
},
"default": [
"ALL"
]
},
"activeStatus": {
"title": "Ad status",
"enum": [
"active",
"inactive",
"all"
],
"type": "string",
"description": "Active ads are running now; inactive ads have stopped but are still in the library.",
"default": "active"
},
"adType": {
"title": "Ad category",
"enum": [
"all",
"political_and_issue_ads",
"housing_ads",
"employment_ads",
"credit_ads"
],
"type": "string",
"description": "Special categories carry extra transparency data (spend, impressions, reach, 'paid for by').",
"default": "all"
},
"mediaType": {
"title": "Media type",
"enum": [
"all",
"image",
"video",
"meme",
"image_and_meme",
"none"
],
"type": "string",
"description": "Creative type. Video is double-checked on every ad.",
"default": "all"
},
"publisherPlatforms": {
"title": "Platforms",
"type": "array",
"description": "Only ads that run on at least one of these platforms. Leave empty for all.",
"items": {
"type": "string",
"enum": [
"facebook",
"instagram",
"messenger",
"audience_network",
"threads",
"whatsapp"
],
"enumTitles": [
"Facebook",
"Instagram",
"Messenger",
"Audience Network",
"Threads",
"WhatsApp"
]
}
},
"contentLanguages": {
"title": "Ad languages",
"type": "array",
"description": "ISO 639-1 codes such as en, es or de. Leave empty for all languages.",
"items": {
"type": "string"
}
},
"searchMode": {
"title": "Keyword match",
"enum": [
"keyword_unordered",
"keyword_exact_phrase"
],
"type": "string",
"description": "Broad matches ads with any of the words; exact phrase matches the words together.",
"default": "keyword_unordered"
},
"sortBy": {
"title": "Sort order",
"enum": [
"relevance",
"most_recent",
"impressions"
],
"type": "string",
"description": "Meta's order of results. With a start date filter or only-new mode, newest first is used automatically so the run can stop early.",
"default": "relevance"
},
"startDateFrom": {
"title": "Started on or after",
"type": "string",
"description": "Only ads that started running on or after this day: 2026-10-01 or an age such as 7 days, 2 weeks, 3 months. Checked on every ad."
},
"startDateTo": {
"title": "Started on or before",
"type": "string",
"description": "Only ads that started running on or before this day (same formats)."
},
"minDaysRunning": {
"title": "Minimum days running",
"minimum": 0,
"type": "integer",
"description": "Only ads that have run for at least this many days. Long-running ads are usually the profitable ones ('winning ads')."
},
"skipDuplicateVersions": {
"title": "One ad per creative group",
"type": "boolean",
"description": "Meta groups versions of the same ad (same creative and text). Turn on to get one row per group and pay for fewer rows.",
"default": false
},
"oneAdPerAdvertiser": {
"title": "One ad per advertiser",
"type": "boolean",
"description": "Keep only the first ad of each advertiser, for example to build a list of who advertises on a keyword.",
"default": false
},
"maxAdsPerSource": {
"title": "Max ads per source",
"minimum": 0,
"type": "integer",
"description": "For each search term and country, Page or URL. 0 = everything Meta returns.",
"default": 200
},
"maxAds": {
"title": "Max ads in total",
"minimum": 0,
"type": "integer",
"description": "Stop the whole run after this many ads. 0 or empty = no limit (your spending limit still applies)."
},
"includeAdDetails": {
"title": "Add EU reach, audience and advertiser details",
"type": "boolean",
"description": "One extra request per ad (charged as ad details): EU reach by country, age and gender, targeted age and gender, payer and beneficiary, advertiser Instagram followers, Page likes, category and verification.",
"default": false
},
"countOnly": {
"title": "Only count ads",
"type": "boolean",
"description": "Return one row per source with the total number of ads Meta reports, without the ads.",
"default": false
},
"includeMarkdown": {
"title": "Add Markdown for AI and reports",
"type": "boolean",
"description": "A compact Markdown summary of each ad in the markdown field, ready for ChatGPT, Claude or a RAG pipeline.",
"default": false
},
"includeRawData": {
"title": "Add Meta's original ad object",
"type": "boolean",
"description": "The full Ad Library JSON in the raw field (contact e-mails and phone numbers removed).",
"default": false
},
"monitoringKey": {
"title": "Watchlist name",
"type": "string",
"description": "Any name, for example nike-daily. Ads delivered under this name are remembered in your account (key-value store facebook-ads-library-watchlists) and rows get isNew and firstSeenDate. Stored encrypted, because a watchlist name can show which brands you track."
},
"onlyNewAds": {
"title": "Only new ads",
"type": "boolean",
"description": "Skip ads that an earlier run of the same watchlist already delivered. Skipped ads are not charged. Results are sorted newest first (unless you pick a sort order), so a run stops soon after it reaches ads you already have.",
"default": false
},
"proxyConfiguration": {
"title": "Proxy",
"type": "object",
"description": "Pages 2+ of Ad Library results need residential IPs, which is the default. The first page, advertiser lookups and ad details use cheaper datacenter IPs automatically.",
"default": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
},
"maxConcurrency": {
"title": "Parallel sources",
"minimum": 1,
"maximum": 16,
"type": "integer",
"description": "How many sources are scraped at the same time, each from its own IP address.",
"default": 4
},
"maxRetries": {
"title": "Retries per request",
"minimum": 1,
"maximum": 20,
"type": "integer",
"description": "A blocked or failed request is retried from a new IP address up to this many times.",
"default": 6
}
}
},
"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
}
}
}
}
}
}
}
}
}
}