{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Scraper", "description": "Every ad a brand runs on Facebook, Instagram and Threads, from the public Meta Ad Library, logged out. Or check in bulk if pages run Meta ads. Page URL, domain or brand input. $0.70 per 1,000 ads, $1 per 1,000 page checks, no start fee. Never more ads or charges than you asked. Empty searches free.", "version": "0.1", "x-build-id": "IuSwyzprBUdGZXp45" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/otterfetch~meta-ad-library/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-otterfetch-meta-ad-library", "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/otterfetch~meta-ad-library/runs": { "post": { "operationId": "runs-sync-otterfetch-meta-ad-library", "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/otterfetch~meta-ad-library/run-sync": { "post": { "operationId": "run-sync-otterfetch-meta-ad-library", "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": { "mode": { "title": "Mode", "enum": [ "ads", "pageCheck" ], "type": "string", "description": "Ads returns the ads each target runs. Page check answers one question per target: is it running Meta ads right now, how many, and the newest and oldest start dates among its first ~30 ads. Page check never walks through the ads. Every checked page is charged, including a page that is running no ads.", "default": "ads" }, "targets": { "title": "Targets", "type": "array", "description": "One per line. Best: a Facebook page URL, which gives exact results. Also accepted: a page ID, an Ad Library link, a website domain (for example jollibee.com.ph) or a brand name or keyword. A page URL gives exact results; domains and brand names are matched and may be ambiguous. Required unless you give an import link.", "items": { "type": "string" } }, "importUrl": { "title": "Import targets from a link", "type": "string", "description": "Optional https link to a CSV file or a Google Sheets link (shared as \"anyone with the link\"). One target per row in the first column; a header row named target, page, url, domain, brand or keyword is skipped. Example: https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID/edit" }, "keywordMode": { "title": "Search brand names as keywords", "type": "boolean", "description": "Off: a brand name is matched to its Facebook page. On: the line is a keyword search across all advertisers.", "default": false }, "country": { "title": "Country", "enum": [ "ALL", "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "CV", "KH", "CM", "CA", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CK", "CR", "CI", "HR", "CW", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "HU", "IS", "IN", "ID", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "RE", "RO", "RU", "RW", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "BS", "GM", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "VI", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VA", "VE", "VN", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "Only ads that reached this country. All countries is the default.", "default": "ALL" }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Which ads to return: running now, stopped, or both.", "default": "active" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ], "type": "string", "description": "Only ads with this kind of media.", "default": "all" }, "platforms": { "title": "Platforms", "type": "array", "description": "Only ads shown on these platforms. Leave empty for all platforms.", "items": { "type": "string", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads" ] } }, "language": { "title": "Language", "enum": [ "any", "ar", "bg", "cs", "da", "de", "el", "en", "es", "et", "fi", "fr", "he", "hi", "hr", "hu", "id", "it", "ja", "ko", "lt", "lv", "ms", "nb", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sr", "sv", "th", "tl", "tr", "uk", "vi", "zh" ], "type": "string", "description": "Only ads written in this language, as detected by Meta.", "default": "any" }, "dateFrom": { "title": "Ran between: from", "type": "string", "description": "Ads that were running at any time between this date and the end date (not only ads that started in the range). Format YYYY-MM-DD. Optional." }, "dateTo": { "title": "Ran between: to", "type": "string", "description": "End of the range. Format YYYY-MM-DD. Optional." }, "sort": { "title": "Sort", "enum": [ "relevance", "impressions", "newest" ], "type": "string", "description": "Order of the ads. Meta does not offer an oldest-first order.", "default": "relevance" }, "maxAdsPerTarget": { "title": "Max ads per target", "minimum": 0, "type": "integer", "description": "Hard limit per target: the run never fetches or bills more. The summary row shows the full total (for example '30 of 4,212 shown'); raise this to get more. 30 is the fastest and cheapest. 0 means no limit, so be careful with large brands.", "default": 30 }, "groupVariants": { "title": "One row per creative", "type": "boolean", "description": "Meta groups near-identical ads. On: one row per group with variant_count and variant_ad_ids, billed once. Off: every ad is its own row, as Meta lists them.", "default": false }, "euDetails": { "title": "EU reach and demographics (+$0.0003 per ad where Meta returned EU or UK data)", "type": "boolean", "description": "Adds total reach and age, gender and country breakdowns for ads shown in the EU or UK, plus payer and beneficiary. Only ads where Meta returned this data are charged. Makes one extra request per ad. Works best with an EU country selected.", "default": false }, "archiveMedia": { "title": "Archive media", "enum": [ "off", "images", "images_videos" ], "type": "string", "description": "Meta media links expire after a few days. Archiving saves the files in this run's key-value store so the links keep working. Priced per archived ad (see the pricing tab); failed downloads are not charged.", "default": "off" }, "maxTargets": { "title": "Max targets", "minimum": 1, "type": "integer", "description": "Optional safety limit for scheduled runs. Extra targets are listed as skipped and not charged." } } }, "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 } } } } } } } } } }