{ "openapi": "3.0.1", "info": { "title": "Meta Ad Library Scraper", "description": "Meta Ad Library scraper for Facebook and Instagram ads, by keyword, Page ID or URL. Each row has the ad copy, creatives, call to action, advertiser Page, run dates and platforms. Spend and impressions exist only on political and issue ads. $0.34 per 1,000 ads.", "version": "0.1", "x-build-id": "txcpyrP7gloUQgfhh" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dami_studio~meta-ads-library-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dami_studio-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/dami_studio~meta-ads-library-scraper/runs": { "post": { "operationId": "runs-sync-dami_studio-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/dami_studio~meta-ads-library-scraper/run-sync": { "post": { "operationId": "run-sync-dami_studio-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. \"nike\" or \"solar panels\". One scrape per term.", "items": { "type": "string" } }, "advertiserPageIds": { "title": "Advertiser Facebook Page IDs", "type": "array", "description": "Numeric Facebook Page IDs to pull every ad for, e.g. \"15087023444\" (Nike). Use this instead of a keyword to get one advertiser's full ad set.", "items": { "type": "string" } }, "adLibraryUrls": { "title": "Ad Library URLs", "type": "array", "description": "Paste facebook.com/ads/library/ URLs straight from your browser. Filters in the URL (country, ad type, active status, platforms, dates, language) are read automatically. A link to one ad (with ?id= in it) returns that ad as one row, billed like any other ad.", "items": { "type": "string" } }, "advertiserPages": { "title": "Advertiser Facebook Pages (links or names)", "type": "array", "description": "Facebook Page links such as facebook.com/nike, or a Page name exactly as Facebook shows it. Each one is matched to the Page in the Ad Library's own Page suggestions, by the handle in the link or by the exact name, and then searched like a Page ID. Nothing close-but-different is used: a Page that does not match exactly gets a free notice row instead.", "items": { "type": "string" } }, "adIds": { "title": "Single ads (IDs or links)", "type": "array", "description": "Ad Library IDs such as 1550534860016399, or ad links with ?id= in them. Each one comes back as one row, billed like any other ad. An ad that is no longer in the Ad Library gets a free notice row.", "items": { "type": "string" } }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code for the Ad Library edition to search, or ALL for every country. Only codes the Ad Library itself offers are accepted; a typo stops the run before anything is searched, with a free notice. UK is read as GB, the code Meta uses.", "default": "US" }, "maxResults": { "title": "Max ads per search", "minimum": 1, "maximum": 20000, "type": "integer", "description": "How many ads to return for each search term, page ID or URL. Meta serves 30 ads up front and 10 per page after that, so 1,000 ads takes about 100 requests and 2-3 minutes.", "default": 100 }, "maxResultsTotal": { "title": "Max ads for the whole run", "minimum": 1, "maximum": 200000, "type": "integer", "description": "Optional. Stops the whole run at this many ads, on top of the cap per search. Ten search terms at 100 each is up to 1,000 ads; set this to 300 and the run stops at 300. Leave empty for no run-wide cap." }, "activeStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Return only ads currently running, only ads that have stopped, or both.", "default": "active" }, "adType": { "title": "Ad category", "enum": [ "all", "political_and_issue_ads", "housing_ads", "employment_ads", "credit_ads" ], "type": "string", "description": "All ads, or only political & issue ads. Impressions, spend, currency, reach and byline are published by Meta for political & issue ads ONLY, pick \"Political and issue ads\" if you need them. On a general search they are empty on ~98% of rows. Housing, employment and credit ads are the categories Meta keeps for those ad types; Meta offers them in some countries only, and any row Meta sends outside the chosen category is left out and not charged.", "default": "all" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video", "meme", "none", "image_and_meme" ], "type": "string", "description": "Filter ads by the kind of creative they use.", "default": "all" }, "searchType": { "title": "Keyword match", "enum": [ "keyword_unordered", "keyword_exact_phrase" ], "type": "string", "description": "Match the words in any order, or as an exact phrase.", "default": "keyword_unordered" }, "limitToPageIds": { "title": "Only these advertiser Page IDs", "type": "array", "description": "Optional. Numeric Page IDs; your search terms then only return ads from these advertisers. Applies to Search terms, not to Page IDs or pasted URLs. Any row from another advertiser is left out and not charged.", "items": { "type": "string" } }, "publisherPlatforms": { "title": "Platforms", "type": "array", "description": "Only return ads shown on these Meta platforms. Leave empty for all of them.", "items": { "type": "string", "enum": [ "FACEBOOK", "INSTAGRAM", "AUDIENCE_NETWORK", "MESSENGER", "THREADS", "WHATSAPP" ], "enumTitles": [ "Facebook", "Instagram", "Audience Network", "Messenger", "Threads", "WhatsApp" ] }, "default": [] }, "startDate": { "title": "Ads running on or after", "type": "string", "description": "YYYY-MM-DD, or a span back from today such as \"7 days\", \"last 3 months\" or \"1 year\" (counted in UTC each time the run starts, which suits a scheduled run). Meta treats this as an OVERLAP window: you get ads that were running at some point in it, not only ads that started in it. Can be set on its own: then you get ads running on or after this date. Measured: a Nike search went from 50,001 matches to 179 with a 2025-01-01 to 2025-03-31 window." }, "endDate": { "title": "Ads running on or before", "type": "string", "description": "YYYY-MM-DD, or a span back from today such as \"yesterday\" or \"30 days\". The other end of the overlap window. Can be set on its own: then you get ads that started on or before this date." }, "sortBy": { "title": "Order", "enum": [ "default", "most_recent", "impressions_high" ], "type": "string", "description": "Meta's own order by default. \"Most recent\" puts the newest ads first. \"Most impressions\" puts the most seen first, and works only where Meta publishes impressions, which means political and issue ads; on other ads the order stays Meta's own. With a cap per search, the order decides which ads you get.", "default": "default" }, "adLanguage": { "title": "Ad language", "type": "string", "description": "Optional. A two-letter language code such as en, es or de: only ads Meta files under that language. Measured on a US Nike search: en kept 10,969 of 21,568 matches, es kept 342." }, "includeAdDetails": { "title": "Include EU transparency and advertiser details", "type": "boolean", "description": "Adds age/gender reach breakdown, reach by region, advertiser page category, page likes, linked Instagram username and follower count, and lifetime political spend. For ads shown in the EU it also adds the total EU reach and who the ad targeted: locations, gender and ages. Also the Page's cover image, its verified status, whether it is a personal profile, and whether its Instagram account is verified. One extra request per ad, so a 1,000-ad run roughly doubles in length. No extra charge.", "default": false }, "includePageTransparency": { "title": "Include Page history and admin countries", "type": "boolean", "description": "Adds the advertiser Page's transparency facts from the Ad Library: the date the Page was created, its name changes and merges, how many people manage it and in which countries (left out when one person manages it, so only the count shows), and a state-controlled media label when Meta gives one. One extra request per advertiser Page, not per ad. No extra charge.", "default": false }, "includePageOwner": { "title": "Include the Page owner's business details", "type": "boolean", "description": "Adds the organisation Meta lists as the confirmed owner of the advertiser Page, as published in the Page's transparency panel: its name, and its city, state, postal code, country and phone where Meta shows them. Business details only, and often empty. Uses the same request as the Page history. No extra charge.", "default": false }, "includeProductData": { "title": "Include product data (optional add-on)", "type": "boolean", "description": "Optional add-on. Reads the product pages an ad links to (up to 10 per ad, on the advertiser's own site) and adds what each page publishes about the product: name, price, currency, brand, image link and rating. Only pages that publish product details are listed; app store links and Facebook links are skipped, and so is any shop that does not answer a plain request.", "default": false }, "countOnly": { "title": "Count only", "type": "boolean", "description": "Returns one row per search term, Page ID, Page or URL with the number of matching ads Meta reports (searchMatchCount), and no ad rows. Each count row is billed like one ad. Meta's count stops at 50,001.", "default": false }, "dedupeAcrossSearches": { "title": "Count an ad once across searches", "type": "boolean", "description": "When two of your searches find the same ad, it is delivered and charged once, under the first search that found it. Off by default, so each search returns its full set.", "default": false }, "runLabel": { "title": "Label for this run", "type": "string", "description": "Optional. Any text, copied into a runLabel column on every row, so batches from scheduled runs are easy to tell apart in one sheet." }, "useApifyDatacenterProxy": { "title": "Use Apify Proxy (optional)", "type": "boolean", "description": "Optional. Adds Apify Proxy as an extra route for the run. Off by default.", "default": false }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Optional. Leave this alone unless you need the run to go out through a particular network. Your own proxy servers are used exactly as given.", "default": { "useApifyProxy": 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 } } } } } } } } } }