{ "openapi": "3.0.1", "info": { "title": "Meta Ads Library Scraper | All Meta Platforms", "description": "Search Meta Ads Library by keyword, country, status, media type, dates, Page ID, URL, or alias. Export deduplicated ads with copy, CTAs, media, placements, counts, and optional advertiser details on Facebook, Instagram, Messenger, Audience Network, Threads, WhatsApp, Oculus, and Streaming Services.", "version": "0.2", "x-build-id": "kDGMVGTGR6DVZjTo3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datascraperes~meta-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datascraperes-meta-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/datascraperes~meta-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-datascraperes-meta-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/datascraperes~meta-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-datascraperes-meta-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": { "query": { "title": "Keyword (one search target required)", "type": "string", "description": "Required unless you provide Page ID or Facebook page URL/alias. Enter a brand, advertiser, product, or exact phrase to search in Meta Ad Library. Examples: ikea, nike, seguros de hogar, or \"black friday\". Leave empty when targeting a specific Facebook page." }, "country": { "title": "Country (optional)", "type": "string", "description": "Optional Meta market code; defaults to ES (Spain). Enter a two-letter code such as ES, US, GB, or FR, or enter ALL to search every available country. Do not enter a full country name such as Spain.", "default": "ES" }, "pageId": { "title": "Page ID (alternative search target)", "type": "string", "description": "Optional alternative to Keyword and page URL. Enter only the numeric Facebook Page ID to collect ads from one advertiser page. Example: 244033170035. Do not paste a URL here; use Facebook page URL or alias instead." }, "pageUrl": { "title": "Facebook page URL or alias (alternative search target)", "type": "string", "description": "Optional alternative to Keyword and Page ID. Enter a public Facebook page URL or exact page alias so the Actor can resolve that advertiser before collecting ads. Examples: https://www.facebook.com/IKEASpain or IKEASpain. Use a Facebook page, not an Instagram profile URL." }, "activeStatus": { "title": "Status (optional)", "enum": [ "ACTIVE", "INACTIVE", "ALL" ], "type": "string", "description": "Optional delivery-status filter; defaults to ACTIVE. Choose ACTIVE for ads currently running, INACTIVE for ads that have stopped, or ALL for both active and inactive ads. Example: choose ACTIVE to monitor current competitor campaigns or ALL to research historical results.", "default": "ACTIVE" }, "mediaType": { "title": "Media type (optional)", "enum": [ "ALL", "IMAGE", "VIDEO", "NONE" ], "type": "string", "description": "Optional creative-format filter; defaults to ALL. Choose IMAGE for image ads, VIDEO for video ads, NONE for ads without image or video media, or ALL for every format. Example: choose VIDEO to build a video-creative library.", "default": "ALL" }, "adType": { "title": "Ad type (optional)", "enum": [ "ALL", "EMPLOYMENT_ADS", "FINANCIAL_PRODUCTS_AND_SERVICES_ADS", "HOUSING_ADS", "POLITICAL_AND_ISSUE_ADS" ], "type": "string", "description": "Optional Meta special-category filter; defaults to ALL. Choose ALL for every topic, EMPLOYMENT for job ads, FINANCIAL PRODUCTS AND SERVICES for financial-related ads, HOUSING for real-estate ads, or POLITICAL AND ISSUE for social issues, elections, and politics. Availability depends on the selected market. Meta's legacy CREDIT_ADS name is not a separate option; use Financial products and services. Example: choose HOUSING_ADS to focus on real-estate ads.", "default": "ALL" }, "publisherPlatforms": { "title": "Publisher platforms (optional)", "maxItems": 8, "uniqueItems": true, "type": "array", "description": "Optional multi-select placement filter; leave empty to include every Meta surface. Choose one or more values from the list: Facebook, Instagram, Messenger, Audience Network, Threads, WhatsApp, Oculus, or Streaming Services. Selecting several keeps an ad when at least one selected platform is present; the output may still list all placements reported by Meta. Example: select Instagram and Facebook to keep ads shown on either surface.", "items": { "type": "string", "enum": [ "FACEBOOK", "INSTAGRAM", "MESSENGER", "AUDIENCE_NETWORK", "THREADS", "WHATSAPP", "OCULUS", "STREAMING_SERVICES" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads", "WhatsApp", "Oculus", "Streaming Services" ] }, "default": [] }, "contentLanguages": { "title": "Content languages", "maxItems": 186, "uniqueItems": true, "type": "array", "description": "Optional multi-select of Meta Ad Library language codes; choose from the dropdown instead of typing. Examples: es (Spanish), en (English), ca (Catalan), pt (Portuguese), cmn (Mandarin Chinese), or yue (Cantonese). Leave empty to include every language.", "items": { "type": "string", "enum": [ "aa", "ab", "ae", "af", "ak", "am", "an", "ar", "as", "av", "ay", "az", "ba", "be", "bg", "bh", "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", "cmn", "yue" ], "enumTitles": [ "Afar", "Abkhazian", "Avestan", "Afrikaans", "Akan", "Amharic", "Aragonese", "Arabic", "Assamese", "Avaric", "Aymara", "Azerbaijani", "Bashkir", "Belarusian", "Bulgarian", "Bihari languages", "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", "Gaelic", "Galician", "Guarani", "Gujarati", "Manx", "Hausa", "Hebrew", "Hindi", "Hiri Motu", "Croatian", "Haitian", "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", "Kirghiz", "Latin", "Luxembourgish", "Ganda", "Limburgan", "Lingala", "Lao", "Lithuanian", "Luba-Katanga", "Latvian", "Malagasy", "Marshallese", "Maori", "Macedonian", "Malayalam", "Mongolian", "Marathi", "Malay", "Maltese", "Burmese", "Nauru", "Norwegian Bokmål", "North Ndebele", "Nepali", "Ndonga", "Dutch", "Norwegian Nynorsk", "Norwegian", "South Ndebele", "Navajo", "Chichewa", "Occitan", "Ojibwa", "Oromo", "Oriya", "Ossetian", "Punjabi", "Pali", "Polish", "Pushto", "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", "Uighur", "Ukrainian", "Urdu", "Uzbek", "Venda", "Vietnamese", "Volapük", "Walloon", "Wolof", "Xhosa", "Yiddish", "Yoruba", "Zhuang", "Chinese", "Zulu", "Mandarin Chinese (ISO 639-3)", "Cantonese (ISO 639-3)" ] }, "default": [] }, "startDate": { "title": "Start date (optional)", "type": "string", "description": "Optional earliest ad start date, in YYYY-MM-DD format. Enter one boundary or use it with End date for a range. Examples: 2026-01-01 or 2026-08-01. Only ads whose reported start_date is on or after this date are kept." }, "endDate": { "title": "End date (optional)", "type": "string", "description": "Optional latest ad start date, in YYYY-MM-DD format. Enter one boundary or use it with Start date for a range. Example: 2026-12-31. Only ads whose reported start_date is on or before this date are kept." }, "maxAds": { "title": "Maximum ads (optional)", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Optional result limit; defaults to 100 unique ads and accepts 1–5,000. The Actor deduplicates by Meta ad archive ID, and each delivered ad creates the base billable events. Use 1 for a quick test, 100 for a normal search, or a higher value for a larger dataset. Example: set 1 to verify the input and output before a larger run.", "default": 100 }, "maxPages": { "title": "Maximum pages (optional)", "minimum": 1, "maximum": 500, "type": "integer", "description": "Optional pagination safety limit; defaults to 100 and accepts 1–500 pages. The Actor stops when this limit is reached even if maxAds has not been met. Use 1–2 for a quick test or 100+ for broad searches; more pages can increase runtime and proxy traffic. Example: set 2 to limit a test to the first two source pages.", "default": 100 }, "includeDetails": { "title": "Enrich ad details (optional)", "type": "boolean", "description": "Optional enrichment switch; defaults to false. Set true when you need advertiser transparency, payer/beneficiary, EU audience, or page-profile details. Example: true. Successful detail responses create the advertiser_details event; unavailable, failed, or skipped details are not billed.", "default": false }, "detailsLimit": { "title": "Maximum enriched ads (optional)", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Optional cap for detail enrichment; defaults to 25 and accepts 1–5,000. It is used only when Enrich ad details is enabled and is ignored when that switch is false. Use 1 to test enrichment or 25 for a normal run. Example: set includeDetails=true and detailsLimit=1 to enrich only the first delivered ad.", "default": 25 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }