{ "openapi": "3.0.1", "info": { "title": "Meta Ads Library Scraper", "description": "[💰 $0.4 / 1K] Extract ads from Meta's public Ad Library across Facebook, Instagram, Messenger, Audience Network, Threads, and WhatsApp. Search by keyword, advertiser page, or Ad Library URL. Returns ad copy, CTAs, advertiser details, dates, platforms, and audience estimates. No login required.", "version": "1.0", "x-build-id": "Yqr48DZgadaQDRONH" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/solidcode~meta-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-solidcode-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/solidcode~meta-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-solidcode-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/solidcode~meta-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-solidcode-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": { "searchTerms": { "title": "Search Terms", "type": "array", "description": "Keywords to search the Ad Library for (e.g. 'electric scooter', 'crypto trading'). Each term runs as its own Ad Library search. Leave empty if you only want to use Page URLs or Start URLs.", "items": { "type": "string" } }, "pageUrls": { "title": "Advertiser Page URLs", "type": "array", "description": "Facebook page URLs (e.g. https://www.facebook.com/nike) or numeric page IDs. Returns every public ad currently or historically run by that advertiser.", "items": { "type": "string" } }, "startUrls": { "title": "Ad Library URLs", "type": "array", "description": "Paste full Meta Ad Library URLs (https://www.facebook.com/ads/library/?...) — every filter encoded in the URL is preserved. Useful when you've already configured a search in the Ad Library UI.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "ALL", "US", "CA", "MX", "BR", "AR", "CL", "CO", "PE", "GB", "IE", "FR", "DE", "ES", "IT", "NL", "BE", "PT", "CH", "AT", "SE", "NO", "DK", "FI", "PL", "CZ", "GR", "RO", "HU", "TR", "IL", "AE", "SA", "EG", "ZA", "NG", "KE", "MA", "IN", "PK", "BD", "ID", "PH", "VN", "TH", "MY", "SG", "JP", "KR", "TW", "HK", "AU", "NZ" ], "type": "string", "description": "Country whose Ad Library to query. Use 'ALL' to search every country at once. Applied to Search Terms and Advertiser Pages; URLs in 'Ad Library URLs' use whatever country is encoded in the URL.", "default": "ALL" }, "adActiveStatus": { "title": "Ad Status", "enum": [ "ALL", "ACTIVE", "INACTIVE" ], "type": "string", "description": "Whether to return only currently-running ads, only stopped/inactive ads, or both. The Ad Library marks ads ACTIVE while they're still being delivered and INACTIVE once they've stopped.", "default": "ALL" }, "adType": { "title": "Ad Category", "enum": [ "ALL", "POLITICAL_AND_ISSUE_ADS", "HOUSING_ADS", "EMPLOYMENT_ADS", "CREDIT_ADS" ], "type": "string", "description": "Meta groups ads into transparency categories. 'All ads' covers every public ad. The other categories surface political/issue, housing, employment, and credit ads where Meta provides additional disclosures (audience estimates, sometimes spend).", "default": "ALL" }, "mediaType": { "title": "Media Type", "enum": [ "ALL", "IMAGE", "VIDEO", "MEME", "NONE" ], "type": "string", "description": "Restrict results by creative format.", "default": "ALL" }, "publisherPlatforms": { "title": "Publisher Platforms", "uniqueItems": true, "type": "array", "description": "Only include ads that ran on these Meta surfaces. Leave empty to include every platform.", "items": { "type": "string", "enum": [ "FACEBOOK", "INSTAGRAM", "MESSENGER", "AUDIENCE_NETWORK", "THREADS", "WHATSAPP" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads", "WhatsApp" ] }, "default": [] }, "languages": { "title": "Ad Languages", "uniqueItems": true, "type": "array", "description": "Only include ads whose creative is in one of these languages. Leave empty for any language.", "items": { "type": "string", "enum": [ "en", "es", "pt", "fr", "de", "it", "nl", "pl", "tr", "ru", "ar", "he", "ja", "ko", "zh", "hi", "id", "th", "vi" ], "enumTitles": [ "English", "Spanish", "Portuguese", "French", "German", "Italian", "Dutch", "Polish", "Turkish", "Russian", "Arabic", "Hebrew", "Japanese", "Korean", "Chinese", "Hindi", "Indonesian", "Thai", "Vietnamese" ] }, "default": [] }, "dateFrom": { "title": "Earliest Start Date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only include ads that first ran on or after this date (YYYY-MM-DD). Leave empty for no lower bound." }, "dateTo": { "title": "Latest Start Date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Only include ads that first ran on or before this date (YYYY-MM-DD). Leave empty for no upper bound." }, "includeAboutPage": { "title": "Enrich with advertiser page data", "type": "boolean", "description": "Look up each advertiser's Facebook page and attach extra fields (category, like count, verified flag, linked Instagram handle, follower count). Each enriched row is billed at the additional 'Advertiser details' rate (see Pricing). Leave off unless you need the page metadata. Disabled when 'Only return total count' is on.", "default": false }, "scrapeAdDetails": { "title": "Include creative details", "type": "boolean", "description": "Attach creative-level details to every ad row (CTA link, headline, card description, snapshot URL, and CTA button label). Each row that gets these fields is billed at the additional 'Creative details' rate (see Pricing). Disabled when 'Only return total count' is on.", "default": false }, "onlyTotalCount": { "title": "Only return total count", "type": "boolean", "description": "Pre-flight mode — return one row per source containing only the total matching-ad count. Useful for sizing a job before committing budget. Each summary row is billed at the 'Total count' rate (much cheaper than full ad collection). Ad rows are not produced and enrichment toggles are ignored.", "default": false }, "maxResults": { "title": "Maximum results", "minimum": 0, "type": "integer", "description": "Cap on total ads collected across every source. Set to 0 for unlimited (the run will keep paginating until Meta returns no more results). Each row is billed at the base 'Ad' rate (plus any enrichment surcharges).", "default": 100 } } }, "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 } } } } } } } } } }