{ "openapi": "3.0.1", "info": { "title": "Meta Facebook Ads Library Scraper", "description": "Scrape ads from the Facebook (Meta) Ad Library by keyword, advertiser page, ad ID or URL: ad copy, images, videos, dates, platforms, spend and impressions ranges, EU reach and targeting. Filters for country, status, media and dates. Cache for new ads only. Export JSON, CSV or Excel.", "version": "1.0", "x-build-id": "spCkGzAHuw88vTgnH" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/confidential_gnat~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-confidential_gnat-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/confidential_gnat~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-confidential_gnat-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/confidential_gnat~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-confidential_gnat-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": { "keywords": { "title": "Keywords", "type": "array", "description": "Search the Ad Library by keyword, brand or phrase. One search is run per keyword. Example: nike", "items": { "type": "string" } }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code (US, GB, DE, FR, BR, IN...), several codes separated by commas (US, GB), or ALL for every country. One search is run per country.", "default": "US" }, "maxItems": { "title": "Max ads per search", "minimum": 1, "type": "integer", "description": "Maximum ads saved for each keyword, advertiser page or URL. Searches too big to scroll through are split into narrower ones automatically.", "default": 5 }, "cacheProjectName": { "title": "Cache project name", "type": "string", "description": "Use the same name on each scheduled run to get only new ads. Ads already saved under that name are skipped, not charged and not counted towards Max ads per search. Each record gets changeType: new. Leave empty to turn the cache off." }, "pages": { "title": "Advertiser pages", "type": "array", "description": "List every ad of an advertiser. Use Facebook page IDs, Facebook page URLs or page names. Example: 15087023444 or https://www.facebook.com/nike", "items": { "type": "string" } }, "startUrls": { "title": "Ad Library URLs", "type": "array", "description": "Ad Library search pages, advertiser views or single ad pages copied from the browser. Their filters are kept. Example: https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&q=nike", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "adIds": { "title": "Ad IDs", "type": "array", "description": "Library IDs of single ads to load, like 1550534860016399.", "items": { "type": "string" } }, "status": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Which ads to include.", "default": "active" }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads" ], "type": "string", "description": "All ads, or the categories that carry spend and audience details.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "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.", "items": { "type": "string", "enum": [ "facebook", "instagram", "audience_network", "messenger", "threads" ], "enumTitles": [ "Facebook", "Instagram", "Audience Network", "Messenger", "Threads" ] } }, "languages": { "title": "Ad languages", "type": "array", "description": "Two-letter language codes of the ad text, like en, de, es. Leave empty for all languages.", "items": { "type": "string" } }, "dateRange": { "title": "Date range", "enum": [ "last24h", "last7d", "last14d", "last30d" ], "type": "string", "description": "Only ads that started in this period. Ignored when Started after is set." }, "startDate": { "title": "Started after", "type": "string", "description": "Only ads that started running on or after this day (YYYY-MM-DD)." }, "endDate": { "title": "Started before", "type": "string", "description": "Only ads that started running on or before this day (YYYY-MM-DD)." }, "exactPhrase": { "title": "Match exact phrase", "type": "boolean", "description": "Search the keyword as one exact phrase instead of any of its words.", "default": false }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "impressions" ], "type": "string", "description": "Most relevant first, or most impressions first (impression ranges are shown for political and issue ads).", "default": "relevance" }, "onlyTotal": { "title": "Only count the ads", "type": "boolean", "description": "Return one row per search with the number of ads the library shows for it (up to 50,000), without reading the ads. Good for tracking how many ads a brand or advertiser runs.", "default": false }, "maxTotalItems": { "title": "Max ads in total", "minimum": 1, "type": "integer", "description": "Optional limit for the whole run, on top of Max ads per search." }, "scrapeDetails": { "title": "Open ad details (page info, EU reach and targeting)", "type": "boolean", "description": "On: the details panel of every ad is opened to add the advertiser's page info (Instagram account, followers, about text, lifetime spend), who paid for the ad and, for ads shown in the EU, the targeting, total reach and the reach by age, gender and country. This is slower, about one extra click per ad. Off: only what the search results show.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy settings for the run. The default works for most searches.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } }