{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper | Ad Creatives", "description": "Collect public Facebook-placement ads from Meta's Ad Library by keyword, Facebook Page ID, or page URL/alias. Export deduplicated ad copy, creatives, media, links, placements, and optional advertiser details to an Apify Dataset.", "version": "0.1", "x-build-id": "eeuZqHRLL7CGCDMCF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datascraperes~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datascraperes-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/datascraperes~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-datascraperes-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/datascraperes~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-datascraperes-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": { "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" }, "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. See Pricing for the configured charge events applied to each delivered ad. 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. If this limit is reached before the ad limit or source end, saved ads remain available and RUN_SUMMARY reports partial collection. 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. Each successfully returned detail payload triggers the optional advertiser_details charge event; unavailable, failed, or skipped details do not trigger that event.", "default": false }, "detailsLimit": { "title": "Maximum enriched ads (optional)", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Optional cap on ads whose details are requested; defaults to 25 and accepts 1–5,000. Unavailable or failed detail results count toward this limit. Used only when Enrich ad details is enabled. Example: set includeDetails=true and detailsLimit=1 to request details for the first eligible 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 }, "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 } } } } } } } } } }