{
"openapi": "3.0.1",
"info": {
"title": "Facebook Ads Library Scraper - Meta Ad Library & Spend",
"description": "Facebook Ads Library scraper for Meta's Ad Library: ads by keyword, advertiser Page or URL with text, images, videos, carousels, dates, platforms, spend, impressions and reach. Filter by country, platform, language, media and date. No login, no cookies. $0.35 per 1,000 ads.",
"version": "0.1",
"x-build-id": "WlNKxTIVPkH8Kgv4c"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/socialscrapers~facebook-ads-library-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-socialscrapers-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/socialscrapers~facebook-ads-library-scraper/runs": {
"post": {
"operationId": "runs-sync-socialscrapers-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/socialscrapers~facebook-ads-library-scraper/run-sync": {
"post": {
"operationId": "run-sync-socialscrapers-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": {
"searchTerms": {
"title": "Search terms",
"type": "array",
"description": "Keywords to search ads for, one search per term, as you would type them into the Ad Library's search box. The filters below apply.",
"items": {
"type": "string"
}
},
"pageUrls": {
"title": "Advertiser Pages",
"type": "array",
"description": "Facebook Pages whose ads you want: a Page URL such as https://www.facebook.com/<page-name>, or the Page's numeric id (the view_all_page_id of an Ad Library link). Share links from the Facebook app (https://www.facebook.com/share/…, fb.me/…) and links to one of the Page's posts work too. The filters below apply.",
"items": {
"type": "string"
}
},
"adLibraryUrls": {
"title": "Ad Library URLs",
"type": "array",
"description": "Searches copied from your browser's address bar on https://www.facebook.com/ads/library/. Every filter in the URL is kept (country, category, status, media, platforms, languages, dates, sorting); a filter the URL does not set comes from the fields below. A link to one ad (?id=...) returns that ad.",
"items": {
"type": "string"
}
},
"country": {
"title": "Country",
"pattern": "^([A-Za-z]{2}|ALL|all|All)$",
"type": "string",
"description": "Where the ads were shown: a two-letter country code such as US, GB or DE, or ALL for every country.",
"default": "ALL"
},
"adType": {
"title": "Ad category",
"enum": [
"all",
"political_and_issue_ads",
"housing_ads",
"employment_ads",
"credit_ads"
],
"type": "string",
"description": "All ads, or only one of the categories the Ad Library keeps extra data for. Political and issue ads come with spend, impressions and the \"Paid for by\" line.",
"default": "all"
},
"activeStatus": {
"title": "Active status",
"enum": [
"active",
"inactive",
"all"
],
"type": "string",
"description": "Ads running now, ads that have 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"
},
"exactPhrase": {
"title": "Exact phrase",
"type": "boolean",
"description": "Match each search term as an exact phrase instead of any order of its words.",
"default": false
},
"dateFrom": {
"title": "Shown from",
"pattern": "^\\s*(?:(?:[tT][oO][dD][aA][yY]|[yY][eE][sS][tT][eE][rR][dD][aA][yY]|[nN][oO][wW])|(?:(?:(?:[tT][hH][eE]\\s+)?(?:[lL][aA][sS][tT]|[pP][aA][sS][tT]|[pP][rR][eE][vV][iI][oO][uU][sS])\\s+)?(?:[-+]\\s*)?(?:\\d{1,5})\\s*|(?:[tT][hH][eE]\\s+)?(?:[lL][aA][sS][tT]|[pP][aA][sS][tT]|[pP][rR][eE][vV][iI][oO][uU][sS])\\s+|[aA][nN]?\\s+)(?:[mM][iI][nN][uU][tT][eE][sS]?|[mM][iI][nN][sS]?|[hH][oO][uU][rR][sS]?|[hH][rR][sS]?|[hH]|[dD][aA][yY][sS]?|[dD]|[wW][eE][eE][kK][sS]?|[wW][kK][sS]?|[wW]|[mM][oO][nN][tT][hH][sS]?|[mM][oO][sS]?|[mM][tT][hH][sS]?|[mM][oO][nN][sS]?|[yY][eE][aA][rR][sS]?|[yY][rR][sS]?|[yY])(?:\\s+[aA][gG][oO])?|(?:(?:19|20)\\d\\d)[-/.](?:0?[1-9]|1[0-2])[-/.](?:0?[1-9]|[12]\\d|3[01])(?:(?:[tT]|\\s+|\\s*,\\s*)(?:[01]?\\d|2[0-3]):(?:[0-5]\\d)(?::(?:[0-5]\\d)(?:[.,](?:\\d{1,9}))?)?\\s*(?:[zZ]|[uU][tT][cC]|[gG][mM][tT]|[+-](?:[01]\\d|2[0-3])(?::?[0-5]\\d)?)?)?|(?:(?:19|20)\\d\\d)(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|(?:(?:19|20)\\d\\d)[-/.](?:0?[1-9]|1[0-2])|(?:(?:19|20)\\d\\d)|(?:1[3-9]|2\\d|3[01])[-/.](?:0?[1-9]|1[0-2])[-/.](?:(?:19|20)\\d\\d)|(?:0?[1-9]|1[0-2])[-/.](?:0?[1-9]|[12]\\d|3[01])[-/.](?:(?:19|20)\\d\\d)|(?:(?:[mM][oO][nN](?:[dD][aA][yY])?|[tT][uU][eE](?:[sS](?:[dD][aA][yY])?)?|[wW][eE][dD](?:[nN][eE][sS][dD][aA][yY])?|[tT][hH][uU](?:[rR](?:[sS](?:[dD][aA][yY])?)?)?|[fF][rR][iI](?:[dD][aA][yY])?|[sS][aA][tT](?:[uU][rR][dD][aA][yY])?|[sS][uU][nN](?:[dD][aA][yY])?)[\\s,.]+)?(?:(?:[jJ][aA][nN](?:[uU][aA][rR][yY])?|[fF][eE][bB](?:[rR][uU][aA][rR][yY])?|[mM][aA][rR](?:[cC][hH])?|[aA][pP][rR](?:[iI][lL])?|[mM][aA][yY]|[jJ][uU][nN][eE]?|[jJ][uU][lL][yY]?|[aA][uU][gG](?:[uU][sS][tT])?|[sS][eE][pP](?:[tT](?:[eE][mM][bB][eE][rR])?)?|[oO][cC][tT](?:[oO][bB][eE][rR])?|[nN][oO][vV](?:[eE][mM][bB][eE][rR])?|[dD][eE][cC](?:[eE][mM][bB][eE][rR])?)[\\s,./-]*(?:(?:0?[1-9]|[12]\\d|3[01])(?:[sS][tT]|[nN][dD]|[rR][dD]|[tT][hH])?[\\s,./-]+)?|(?:0?[1-9]|[12]\\d|3[01])(?:[sS][tT]|[nN][dD]|[rR][dD]|[tT][hH])?[\\s,./-]*(?:[oO][fF]\\s+)?(?:[jJ][aA][nN](?:[uU][aA][rR][yY])?|[fF][eE][bB](?:[rR][uU][aA][rR][yY])?|[mM][aA][rR](?:[cC][hH])?|[aA][pP][rR](?:[iI][lL])?|[mM][aA][yY]|[jJ][uU][nN][eE]?|[jJ][uU][lL][yY]?|[aA][uU][gG](?:[uU][sS][tT])?|[sS][eE][pP](?:[tT](?:[eE][mM][bB][eE][rR])?)?|[oO][cC][tT](?:[oO][bB][eE][rR])?|[nN][oO][vV](?:[eE][mM][bB][eE][rR])?|[dD][eE][cC](?:[eE][mM][bB][eE][rR])?)[\\s,./-]*)(?:(?:19|20)\\d\\d)|(?:(?:19|20)\\d\\d)[\\s,./-]*(?:[jJ][aA][nN](?:[uU][aA][rR][yY])?|[fF][eE][bB](?:[rR][uU][aA][rR][yY])?|[mM][aA][rR](?:[cC][hH])?|[aA][pP][rR](?:[iI][lL])?|[mM][aA][yY]|[jJ][uU][nN][eE]?|[jJ][uU][lL][yY]?|[aA][uU][gG](?:[uU][sS][tT])?|[sS][eE][pP](?:[tT](?:[eE][mM][bB][eE][rR])?)?|[oO][cC][tT](?:[oO][bB][eE][rR])?|[nN][oO][vV](?:[eE][mM][bB][eE][rR])?|[dD][eE][cC](?:[eE][mM][bB][eE][rR])?)[\\s,./-]*(?:0?[1-9]|[12]\\d|3[01])(?:[sS][tT]|[nN][dD]|[rR][dD]|[tT][hH])?)?\\s*$",
"type": "string",
"description": "Only ads shown on or after this day. Pick a date or an age, or type one: a date (2026-01-31, 31/01/2026, Jan 31 2026) or an age such as 30 days, 7 days, 2w or 3 months. This is the Ad Library's date filter: an ad that started earlier but still ran on that day is included."
},
"dateTo": {
"title": "Shown until",
"pattern": "^\\s*(?:(?:[tT][oO][dD][aA][yY]|[yY][eE][sS][tT][eE][rR][dD][aA][yY]|[nN][oO][wW])|(?:(?:(?:[tT][hH][eE]\\s+)?(?:[lL][aA][sS][tT]|[pP][aA][sS][tT]|[pP][rR][eE][vV][iI][oO][uU][sS])\\s+)?(?:[-+]\\s*)?(?:\\d{1,5})\\s*|(?:[tT][hH][eE]\\s+)?(?:[lL][aA][sS][tT]|[pP][aA][sS][tT]|[pP][rR][eE][vV][iI][oO][uU][sS])\\s+|[aA][nN]?\\s+)(?:[mM][iI][nN][uU][tT][eE][sS]?|[mM][iI][nN][sS]?|[hH][oO][uU][rR][sS]?|[hH][rR][sS]?|[hH]|[dD][aA][yY][sS]?|[dD]|[wW][eE][eE][kK][sS]?|[wW][kK][sS]?|[wW]|[mM][oO][nN][tT][hH][sS]?|[mM][oO][sS]?|[mM][tT][hH][sS]?|[mM][oO][nN][sS]?|[yY][eE][aA][rR][sS]?|[yY][rR][sS]?|[yY])(?:\\s+[aA][gG][oO])?|(?:(?:19|20)\\d\\d)[-/.](?:0?[1-9]|1[0-2])[-/.](?:0?[1-9]|[12]\\d|3[01])(?:(?:[tT]|\\s+|\\s*,\\s*)(?:[01]?\\d|2[0-3]):(?:[0-5]\\d)(?::(?:[0-5]\\d)(?:[.,](?:\\d{1,9}))?)?\\s*(?:[zZ]|[uU][tT][cC]|[gG][mM][tT]|[+-](?:[01]\\d|2[0-3])(?::?[0-5]\\d)?)?)?|(?:(?:19|20)\\d\\d)(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])|(?:(?:19|20)\\d\\d)[-/.](?:0?[1-9]|1[0-2])|(?:(?:19|20)\\d\\d)|(?:1[3-9]|2\\d|3[01])[-/.](?:0?[1-9]|1[0-2])[-/.](?:(?:19|20)\\d\\d)|(?:0?[1-9]|1[0-2])[-/.](?:0?[1-9]|[12]\\d|3[01])[-/.](?:(?:19|20)\\d\\d)|(?:(?:[mM][oO][nN](?:[dD][aA][yY])?|[tT][uU][eE](?:[sS](?:[dD][aA][yY])?)?|[wW][eE][dD](?:[nN][eE][sS][dD][aA][yY])?|[tT][hH][uU](?:[rR](?:[sS](?:[dD][aA][yY])?)?)?|[fF][rR][iI](?:[dD][aA][yY])?|[sS][aA][tT](?:[uU][rR][dD][aA][yY])?|[sS][uU][nN](?:[dD][aA][yY])?)[\\s,.]+)?(?:(?:[jJ][aA][nN](?:[uU][aA][rR][yY])?|[fF][eE][bB](?:[rR][uU][aA][rR][yY])?|[mM][aA][rR](?:[cC][hH])?|[aA][pP][rR](?:[iI][lL])?|[mM][aA][yY]|[jJ][uU][nN][eE]?|[jJ][uU][lL][yY]?|[aA][uU][gG](?:[uU][sS][tT])?|[sS][eE][pP](?:[tT](?:[eE][mM][bB][eE][rR])?)?|[oO][cC][tT](?:[oO][bB][eE][rR])?|[nN][oO][vV](?:[eE][mM][bB][eE][rR])?|[dD][eE][cC](?:[eE][mM][bB][eE][rR])?)[\\s,./-]*(?:(?:0?[1-9]|[12]\\d|3[01])(?:[sS][tT]|[nN][dD]|[rR][dD]|[tT][hH])?[\\s,./-]+)?|(?:0?[1-9]|[12]\\d|3[01])(?:[sS][tT]|[nN][dD]|[rR][dD]|[tT][hH])?[\\s,./-]*(?:[oO][fF]\\s+)?(?:[jJ][aA][nN](?:[uU][aA][rR][yY])?|[fF][eE][bB](?:[rR][uU][aA][rR][yY])?|[mM][aA][rR](?:[cC][hH])?|[aA][pP][rR](?:[iI][lL])?|[mM][aA][yY]|[jJ][uU][nN][eE]?|[jJ][uU][lL][yY]?|[aA][uU][gG](?:[uU][sS][tT])?|[sS][eE][pP](?:[tT](?:[eE][mM][bB][eE][rR])?)?|[oO][cC][tT](?:[oO][bB][eE][rR])?|[nN][oO][vV](?:[eE][mM][bB][eE][rR])?|[dD][eE][cC](?:[eE][mM][bB][eE][rR])?)[\\s,./-]*)(?:(?:19|20)\\d\\d)|(?:(?:19|20)\\d\\d)[\\s,./-]*(?:[jJ][aA][nN](?:[uU][aA][rR][yY])?|[fF][eE][bB](?:[rR][uU][aA][rR][yY])?|[mM][aA][rR](?:[cC][hH])?|[aA][pP][rR](?:[iI][lL])?|[mM][aA][yY]|[jJ][uU][nN][eE]?|[jJ][uU][lL][yY]?|[aA][uU][gG](?:[uU][sS][tT])?|[sS][eE][pP](?:[tT](?:[eE][mM][bB][eE][rR])?)?|[oO][cC][tT](?:[oO][bB][eE][rR])?|[nN][oO][vV](?:[eE][mM][bB][eE][rR])?|[dD][eE][cC](?:[eE][mM][bB][eE][rR])?)[\\s,./-]*(?:0?[1-9]|[12]\\d|3[01])(?:[sS][tT]|[nN][dD]|[rR][dD]|[tT][hH])?)?\\s*$",
"type": "string",
"description": "Only ads shown on or before this day: a date (2026-01-31, 31/01/2026, Jan 31 2026) or an age such as 7 days or yesterday."
},
"platforms": {
"title": "Platforms",
"type": "array",
"description": "Only ads shown on these platforms, for example Instagram only. Leave empty for every platform.",
"items": {
"type": "string",
"enum": [
"facebook",
"instagram",
"audience_network",
"messenger",
"threads",
"whatsapp"
],
"enumTitles": [
"Facebook",
"Instagram",
"Audience Network",
"Messenger",
"Threads",
"WhatsApp"
]
}
},
"languages": {
"title": "Ad languages",
"type": "array",
"description": "Only ads in these languages: two-letter codes such as en, es or de, one per line. Leave empty for every language.",
"items": {
"type": "string"
}
},
"sortBy": {
"title": "Sort by",
"enum": [
"default",
"impressions_high",
"impressions_low"
],
"type": "string",
"description": "The Ad Library's own order (the default), or ads with the most or the fewest impressions first.",
"default": "default"
},
"maxAds": {
"title": "Max ads per search",
"minimum": 0,
"type": "integer",
"description": "How many ads to collect for each search term, Page and Ad Library URL, for example 1000. 0 = every ad the search lists.",
"default": 100
},
"includeAdDetails": {
"title": "Include ad details",
"type": "boolean",
"description": "Also open each ad's details: the audience by age, gender and region for political and issue ads; reach, targeting, payer and beneficiary for ads shown in the European Union; the advertiser's Page facts. Slower (one more request per ad); the price per ad is the same.",
"default": false
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Apify Proxy RESIDENTIAL (the default) is recommended: Facebook refuses many data-center IP addresses. Apify Proxy without the RESIDENTIAL group is switched to RESIDENTIAL (your country is kept), because Facebook turns datacenter IPs away; residential traffic is included in the price.",
"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
}
}
}
}
}
}
}
}
}
}