{ "openapi": "3.0.1", "info": { "title": "Meta Ad Library API: Facebook Ads Library", "description": "Search the Meta (Facebook and Instagram) Ad Library by keyword, advertiser or Ad Library URL, in any country. Ad text, images, videos, landing pages, dates and platforms, plus optional advertiser details and EU reach. Monitor advertisers for new ads. No login.", "version": "0.2", "x-build-id": "ZSRHhv7d4WX6JHgd5" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/deepmine~meta-ad-library/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-deepmine-meta-ad-library", "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/deepmine~meta-ad-library/runs": { "post": { "operationId": "runs-sync-deepmine-meta-ad-library", "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/deepmine~meta-ad-library/run-sync": { "post": { "operationId": "run-sync-deepmine-meta-ad-library", "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": { "searchQueries": { "title": "Search terms", "type": "array", "description": "Keywords to search ads for, as you'd type them in the Ad Library search box. One search per line.", "items": { "type": "string" } }, "advertisers": { "title": "Advertisers", "type": "array", "description": "Advertisers whose ads you want: a Facebook page link (facebook.com/nike), a page id, an Ad Library link of the advertiser, or the page name exactly as it shows on its ads.", "items": { "type": "string" } }, "country": { "title": "Country", "type": "string", "description": "Two-letter country code where the ads ran (US, GB, DE, ...), or ALL for every country.", "default": "ALL" }, "maxAdsPerQuery": { "title": "Max ads per search", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop each search, advertiser or URL after this many ads. You pay per ad, so this caps the cost of each search. Ads come most impressions first (with Only new ads, most recent first, and this limits the new ads per run). About 3 minutes per 1,000 ads.", "default": 200 }, "includeAdDetails": { "title": "Include ad details", "type": "boolean", "description": "Also fetch each ad's details: the advertiser's verification and Instagram account and followers and, for ads shown in the EU or UK, the reach, reach by country, targeted ages and gender, plus the payer and beneficiary (Meta's full details, with reach by age and gender, are in ad_details). An ad with details costs more than a plain ad (see Pricing), and each needs one more request, so runs are slower. An ad whose details fail is charged as a plain ad.", "default": false }, "onlyNewAds": { "title": "Only new ads (monitor)", "type": "boolean", "description": "Return only ads started since the last run that this Actor hasn't returned before for the same search, reading up to 1,000 ads past Max ads per search to find them. You pay only for the new ads. Schedule the run (e.g. daily) to monitor advertisers or keywords. The first run returns the newest ads, up to Max ads per search.", "default": false }, "startUrls": { "title": "Ad Library URLs", "type": "array", "description": "Searches copied from facebook.com/ads/library in your browser. The filters in the link (country, active status, media type, dates) are used.", "items": { "type": "string" } }, "activeStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Only active ads, only ads that 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" }, "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 carry spend and impressions ranges).", "default": "all" }, "exactPhrase": { "title": "Exact phrase", "type": "boolean", "description": "Match the search terms as an exact phrase instead of any order.", "default": false }, "dateFrom": { "title": "Shown on or after", "type": "string", "description": "Only ads that were shown on or after this date (YYYY-MM-DD), whatever day they started. This is the Ad Library's own date filter." }, "dateTo": { "title": "Shown on or before", "type": "string", "description": "Only ads that were shown on or before this date (YYYY-MM-DD)." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Residential proxies are the default and recommended: Meta refuses most datacenter IPs past the first page of results.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } } } }, "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 } } } } } } } } } }