{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper — Meta & Instagram", "description": "Scrape Facebook Ad Library and Meta ads by advertiser, keyword, or URL. Get ad copy, images, videos, carousel cards, links, dates, and optional EU data. Export JSON, CSV, or Excel for competitor ad research. Pay only for successful saved ads.", "version": "0.1", "x-build-id": "5RdSOdvjaQm6jXhYi" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/chronometrica~facebook-ads-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-chronometrica-facebook-ads-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/chronometrica~facebook-ads-scraper/runs": { "post": { "operationId": "runs-sync-chronometrica-facebook-ads-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/chronometrica~facebook-ads-scraper/run-sync": { "post": { "operationId": "run-sync-chronometrica-facebook-ads-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": { "targets": { "title": "Pages, Ad Library URLs, or keywords", "minItems": 0, "maxItems": 40, "type": "array", "description": "Add up to 40 entries. Use a Facebook page URL or numeric page ID to find that advertiser’s ads. Enter keywords to search across advertisers. Paste an Ad Library URL to keep its supported filters. For one exact ad, use its Library URL with id=. Each entry starts a separate search. The total ad limit covers all entries and countries.", "items": { "type": "string", "minLength": 1 } }, "maxAds": { "title": "Total ad limit — all inputs", "minimum": 0, "type": "integer", "description": "Set one total saved-ad limit for all entries and countries. The API default is 100; the form starts with 10. Use 0 for no ad-count cap. Spending, time, and source limits still apply. An ad with several creative cards counts as one ad. Count mode ignores this limit.", "default": 100 }, "countries": { "title": "Countries — blank uses URL or United States", "minItems": 0, "maxItems": 5, "uniqueItems": true, "type": "array", "description": "Leave blank to use each Ad Library URL’s country. Page IDs, page URLs, and keywords use United States when no country is set. To choose your own search countries, select 1–5. Select All countries on its own. Your choice must agree with a country in a pasted URL. The country sets the Library search scope. It does not prove ad targeting or reach.", "items": { "type": "string", "enum": [ "ALL", "AX", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "KY", "CF", "TD", "CL", "CO", "KM", "CK", "CR", "CI", "HR", "CW", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "ET", "FK", "FO", "FM", "FJ", "FI", "FR", "GF", "GA", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HN", "HU", "IS", "IN", "ID", "IQ", "IE", "IM", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MK", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NZ", "NI", "NE", "NG", "NU", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "RE", "RO", "RW", "BL", "SH", "KN", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "SS", "ES", "LK", "LC", "SR", "SJ", "SZ", "SE", "CH", "TW", "TJ", "TZ", "TH", "BS", "GM", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "UY", "VI", "UZ", "VU", "VA", "VE", "VN", "YE", "ZM", "ZW", "AF", "CN", "CX", "CC", "PF", "TF", "HM", "HK", "IL", "MO", "AN", "NC", "NF", "RU", "KR", "WF", "EH" ], "enumTitles": [ "All countries", "Åland Islands (AX)", "Albania (AL)", "Algeria (DZ)", "American Samoa (AS)", "Andorra (AD)", "Angola (AO)", "Anguilla (AI)", "Antarctica (AQ)", "Antigua & Barbuda (AG)", "Argentina (AR)", "Armenia (AM)", "Aruba (AW)", "Australia (AU)", "Austria (AT)", "Azerbaijan (AZ)", "Bahrain (BH)", "Bangladesh (BD)", "Barbados (BB)", "Belarus (BY)", "Belgium (BE)", "Belize (BZ)", "Benin (BJ)", "Bermuda (BM)", "Bhutan (BT)", "Bolivia (BO)", "Caribbean Netherlands (BQ)", "Bosnia & Herzegovina (BA)", "Botswana (BW)", "Bouvet Island (BV)", "Brazil (BR)", "British Indian Ocean Territory (IO)", "British Virgin Islands (VG)", "Brunei (BN)", "Bulgaria (BG)", "Burkina Faso (BF)", "Burundi (BI)", "Cambodia (KH)", "Cameroon (CM)", "Canada (CA)", "Cape Verde (CV)", "Cayman Islands (KY)", "Central African Republic (CF)", "Chad (TD)", "Chile (CL)", "Colombia (CO)", "Comoros (KM)", "Cook Islands (CK)", "Costa Rica (CR)", "Côte d’Ivoire (CI)", "Croatia (HR)", "Curaçao (CW)", "Cyprus (CY)", "Czechia (CZ)", "Congo - Kinshasa (CD)", "Denmark (DK)", "Djibouti (DJ)", "Dominica (DM)", "Dominican Republic (DO)", "Ecuador (EC)", "Egypt (EG)", "El Salvador (SV)", "Equatorial Guinea (GQ)", "Eritrea (ER)", "Estonia (EE)", "Ethiopia (ET)", "Falkland Islands (FK)", "Faroe Islands (FO)", "Micronesia (FM)", "Fiji (FJ)", "Finland (FI)", "France (FR)", "French Guiana (GF)", "Gabon (GA)", "Georgia (GE)", "Germany (DE)", "Ghana (GH)", "Gibraltar (GI)", "Greece (GR)", "Greenland (GL)", "Grenada (GD)", "Guadeloupe (GP)", "Guam (GU)", "Guatemala (GT)", "Guernsey (GG)", "Guinea (GN)", "Guinea-Bissau (GW)", "Guyana (GY)", "Haiti (HT)", "Honduras (HN)", "Hungary (HU)", "Iceland (IS)", "India (IN)", "Indonesia (ID)", "Iraq (IQ)", "Ireland (IE)", "Isle of Man (IM)", "Italy (IT)", "Jamaica (JM)", "Japan (JP)", "Jersey (JE)", "Jordan (JO)", "Kazakhstan (KZ)", "Kenya (KE)", "Kiribati (KI)", "Kosovo (XK)", "Kuwait (KW)", "Kyrgyzstan (KG)", "Laos (LA)", "Latvia (LV)", "Lebanon (LB)", "Lesotho (LS)", "Liberia (LR)", "Libya (LY)", "Liechtenstein (LI)", "Lithuania (LT)", "Luxembourg (LU)", "North Macedonia (MK)", "Madagascar (MG)", "Malawi (MW)", "Malaysia (MY)", "Maldives (MV)", "Mali (ML)", "Malta (MT)", "Marshall Islands (MH)", "Martinique (MQ)", "Mauritania (MR)", "Mauritius (MU)", "Mayotte (YT)", "Mexico (MX)", "Moldova (MD)", "Monaco (MC)", "Mongolia (MN)", "Montenegro (ME)", "Montserrat (MS)", "Morocco (MA)", "Mozambique (MZ)", "Myanmar (Burma) (MM)", "Namibia (NA)", "Nauru (NR)", "Nepal (NP)", "Netherlands (NL)", "New Zealand (NZ)", "Nicaragua (NI)", "Niger (NE)", "Nigeria (NG)", "Niue (NU)", "Northern Mariana Islands (MP)", "Norway (NO)", "Oman (OM)", "Pakistan (PK)", "Palau (PW)", "Palestinian Territories (PS)", "Panama (PA)", "Papua New Guinea (PG)", "Paraguay (PY)", "Peru (PE)", "Philippines (PH)", "Pitcairn Islands (PN)", "Poland (PL)", "Portugal (PT)", "Puerto Rico (PR)", "Qatar (QA)", "Congo - Brazzaville (CG)", "Réunion (RE)", "Romania (RO)", "Rwanda (RW)", "St. Barthélemy (BL)", "St. Helena (SH)", "St. Kitts & Nevis (KN)", "St. Martin (MF)", "St. Pierre & Miquelon (PM)", "St. Vincent & Grenadines (VC)", "Samoa (WS)", "San Marino (SM)", "São Tomé & Príncipe (ST)", "Saudi Arabia (SA)", "Senegal (SN)", "Serbia (RS)", "Seychelles (SC)", "Sierra Leone (SL)", "Singapore (SG)", "Sint Maarten (SX)", "Slovakia (SK)", "Slovenia (SI)", "Solomon Islands (SB)", "Somalia (SO)", "South Africa (ZA)", "South Georgia & South Sandwich Islands (GS)", "South Sudan (SS)", "Spain (ES)", "Sri Lanka (LK)", "St. Lucia (LC)", "Suriname (SR)", "Svalbard & Jan Mayen (SJ)", "Eswatini (SZ)", "Sweden (SE)", "Switzerland (CH)", "Taiwan (TW)", "Tajikistan (TJ)", "Tanzania (TZ)", "Thailand (TH)", "Bahamas (BS)", "Gambia (GM)", "Timor-Leste (TL)", "Togo (TG)", "Tokelau (TK)", "Tonga (TO)", "Trinidad & Tobago (TT)", "Tunisia (TN)", "Türkiye (TR)", "Turkmenistan (TM)", "Turks & Caicos Islands (TC)", "Tuvalu (TV)", "Uganda (UG)", "Ukraine (UA)", "United Arab Emirates (AE)", "United Kingdom (GB)", "United States (US)", "U.S. Outlying Islands (UM)", "Uruguay (UY)", "U.S. Virgin Islands (VI)", "Uzbekistan (UZ)", "Vanuatu (VU)", "Vatican City (VA)", "Venezuela (VE)", "Vietnam (VN)", "Yemen (YE)", "Zambia (ZM)", "Zimbabwe (ZW)", "Afghanistan (AF)", "China (CN)", "Christmas Island (CX)", "Cocos (Keeling) Islands (CC)", "French Polynesia (PF)", "French Southern Territories (TF)", "Heard & McDonald Islands (HM)", "Hong Kong SAR China (HK)", "Israel (IL)", "Macao SAR China (MO)", "Curaçao (AN)", "New Caledonia (NC)", "Norfolk Island (NF)", "Russia (RU)", "South Korea (KR)", "Wallis & Futuna (WF)", "Western Sahara (EH)" ] } }, "activeStatus": { "title": "Active status", "enum": [ "auto", "active", "inactive", "all" ], "type": "string", "description": "Use URL setting follows the status in a pasted Ad Library URL. Other inputs use active ads. Your explicit choice must agree with the URL. Meta may not expose all inactive ads." }, "adType": { "title": "Ad category", "enum": [ "auto", "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads" ], "type": "string", "description": "Choose an ad category, or follow the Ad Library URL. Without a URL category, the default is all categories. A category does not guarantee spend or reach data." }, "mediaType": { "title": "Media type", "enum": [ "auto", "all", "image", "video" ], "type": "string", "description": "Choose image ads, video ads, or all media. Use URL setting follows a pasted Ad Library URL; other inputs use all media. A dynamic ad can contain several media types." }, "publisherPlatforms": { "title": "Platforms — blank follows URL or all", "maxItems": 4, "uniqueItems": true, "type": "array", "description": "Select publisher platforms, or leave empty to keep URL filters and otherwise search all platforms. An explicit selection must agree with a pasted URL.", "items": { "type": "string", "enum": [ "facebook", "instagram", "messenger", "audience_network" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network" ] } }, "contentLanguages": { "title": "Languages — blank follows URL or all", "maxItems": 10, "uniqueItems": true, "type": "array", "description": "Choose a suggested language or enter a two-letter code in lower case, such as en. Leave blank to follow the Ad Library URL, or search all languages when the URL has no language filter. Your explicit choice must agree with the URL.", "items": { "type": "string", "enumSuggestedValues": [ "en", "es", "fr", "de", "pt", "it", "nl", "ar", "hi", "ja", "ko", "zh" ], "enumTitles": [ "English (en)", "Spanish (es)", "French (fr)", "German (de)", "Portuguese (pt)", "Italian (it)", "Dutch (nl)", "Arabic (ar)", "Hindi (hi)", "Japanese (ja)", "Korean (ko)", "Chinese (zh)" ] } }, "searchMode": { "title": "Keyword matching", "enum": [ "auto", "broad", "exactPhrase" ], "type": "string", "description": "Follow a pasted keyword search mode, or choose broad match or an exact phrase. The default for plain keywords is broad. This does not filter an advertiser by an added keyword; each input is a separate search." }, "sortBy": { "title": "Sort order", "enum": [ "auto", "impressions", "recent", "activeTime" ], "type": "string", "description": "Follow the URL sort, or choose an order within each search. The default is most impressions. Recent uses Meta’s relevance groups by month, not a strict start-date sort. Inputs stay in input order; there is no combined sort. Exact-ad URLs ignore this choice." }, "startDatePreset": { "title": "Ads started", "enum": [ "any", "last7", "last30", "custom" ], "type": "string", "description": "Any time applies no start-date filter. Last 7 days and Last 30 days include today in UTC. Choose Custom start dates to enter at least one date below. Do not combine another preset with custom dates." }, "startedOnOrAfter": { "title": "Started on or after", "type": "string", "description": "Optional inclusive source ad start date in YYYY-MM-DD, measured in UTC. Omit for no lower bound. This tests when the ad started, not whether it was active during a date window. Date filtering can require reading more candidates." }, "startedOnOrBefore": { "title": "Started on or before", "type": "string", "description": "Optional inclusive source ad start date in YYYY-MM-DD, measured in UTC. Omit for no upper bound. Must not be earlier than startedOnOrAfter. Ads without a valid source start time cannot satisfy a date filter." }, "activeOnOrAfter": { "title": "Active on or after", "type": "string", "description": "Keep ads whose source delivery interval overlaps this date or a later date. Inclusive YYYY-MM-DD in UTC. A currently active ad has no known delivery end. Missing dates needed to decide overlap produce an incomplete input outcome. Omit for no lower bound. Collection checks this filter before details and saving; selective windows can take longer. Not supported in count mode." }, "activeOnOrBefore": { "title": "Active on or before", "type": "string", "description": "Keep ads whose source delivery interval overlaps this date or an earlier date. Inclusive YYYY-MM-DD in UTC. Must not be earlier than activeOnOrAfter. May be combined with start-date filters. Omit for no upper bound. Collection checks this filter before details and saving; selective windows can take longer. Not supported in count mode." }, "mode": { "title": "What to return", "enum": [ "ads", "count" ], "type": "string", "description": "Choose Ad records to save unique ads. Choose Counts only to read Meta’s reported total from the first result page of each search. Totals appear in the run summary. Counts only saves no ad rows and has no Actor event charge. Totals can be approximate, overlap across searches, or be unavailable. Counts only does not support date filters or extra data.", "default": "ads" }, "details": { "title": "Extra data", "enum": [ "none", "advertiser", "transparency", "all" ], "type": "string", "description": "Standard ad data includes ad copy, creative cards, links, and media URLs. Add public advertiser and Instagram details, audience and payer disclosures, or both. There is no extra ad fee, but collection can take longer. Meta may not expose every field; missing values stay null. Keep Standard ad data for Counts only.", "default": "none" }, "searchTerms": { "title": "Search terms", "minItems": 0, "maxItems": 20, "type": "array", "description": "Compatibility input for existing API calls: up to 20 keyword searches. New form users can put keywords in targets. If both fields are supplied, their entries are separate searches and share the total ad limit.", "items": { "type": "string", "minLength": 1 } } } }, "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 } } } } } } } } } }