{ "openapi": "3.0.1", "info": { "title": "Facebook Ads Library Scraper: Meta Ad Library API", "description": "Scrape Meta's Facebook Ad Library by keyword or advertiser in any country: ad text, images, videos, start date, days running, platforms, EU reach and age/gender data, plus a plain-English summary per advertiser. $0.50 per 1,000 ads.", "version": "1.0", "x-build-id": "ZXyV7i6o1ZmoagCKm" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/meridianlabs~facebook-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-meridianlabs-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/meridianlabs~facebook-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-meridianlabs-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/meridianlabs~facebook-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-meridianlabs-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": { "advertisers": { "title": "Advertisers", "type": "array", "description": "Brands whose ads you want: a name (Nike), a Facebook page link (facebook.com/nike), a numeric page ID, or an Ad Library link with view_all_page_id. Names are matched the way the Ad Library search box does; the status row shows which page was used. Each advertiser also gets a free summary row.", "items": { "type": "string" } }, "searchTerms": { "title": "Search terms", "type": "array", "description": "Words to search ad text for, like the Ad Library search box (one search per term and country).", "items": { "type": "string" } }, "adLibraryUrls": { "title": "Ad Library links", "type": "array", "description": "Paste searches from facebook.com/ads/library: each keeps its own country, active status, media type and date filters.", "items": { "type": "string" } }, "countries": { "title": "Countries", "type": "array", "description": "Two-letter country codes where the ads were shown: US, GB, DE, FR, AU... (UK also works), or ALL for every country. Each search runs once per country.", "default": [ "US" ], "items": { "type": "string" } }, "maxAdsPerSearch": { "title": "Max ads per search", "minimum": 1, "maximum": 10000, "type": "integer", "description": "The most ads to return for each search term or advertiser in each country, in the order the Ad Library shows them. You pay per ad, so this is also your cost cap.", "default": 100 }, "activeStatus": { "title": "Active status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Inactive ads show how long an ad ran before it was switched off.", "default": "active" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "image_and_meme", "none" ], "type": "string", "description": "Only ads with this kind of creative, like the Ad Library's media type filter.", "default": "all" }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads" ], "type": "string", "description": "All ads, or only ads about social issues, elections or politics (these also carry Meta's spend and impressions ranges).", "default": "all" }, "dateFrom": { "title": "Shown from", "type": "string", "description": "Only ads that were shown on or after this date (the Ad Library's \"impressions by date\" filter). An ad that started earlier but was still running counts." }, "dateTo": { "title": "Shown until", "type": "string", "description": "Only ads that were shown on or before this date." }, "exactPhrase": { "title": "Exact phrase", "type": "boolean", "description": "Match search terms as an exact phrase instead of any order.", "default": false }, "includeAdvertiserSummary": { "title": "Advertiser summaries", "type": "boolean", "description": "Adds a free summary row per advertiser you searched for, and per advertiser with 3+ ads in the run: ad counts, active count, oldest and newest ads, longest-running ad, formats, platforms, landing sites, recurring wording, and a one-paragraph plain-English summary.", "default": true }, "includeEuDetails": { "title": "EU transparency data", "type": "boolean", "description": "For ads shown in the EU: total EU reach, reach by country, age and gender, the targeting (locations, ages, gender) and who paid and who benefits. One extra lookup per ad, so runs take longer; same price per ad.", "default": false }, "maxConcurrency": { "title": "Searches at once", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many searches run in parallel.", "default": 5 }, "failOnErrors": { "title": "Fail the run if a search fails", "type": "boolean", "description": "For schedules and monitoring: mark the run failed (so Apify alerts you) if any search fails or stops early. Ads already saved are kept.", "default": false } } }, "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 } } } } } } } } } }