{ "openapi": "3.0.1", "info": { "title": "Meta Ad Spy", "description": "Meta Ad Spy scrapes Facebook Ads Library to find winning products, dropshipping trends, and top Shopify ad angles. Discover long-running Meta ads, top CTAs, hooks, formats, and competitor creatives by keyword to validate products before you spend.", "version": "0.2", "x-build-id": "YbrFVeXNh8ZU18kke" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/deepmine~meta-ad-spy/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-deepmine-meta-ad-spy", "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-spy/runs": { "post": { "operationId": "runs-sync-deepmine-meta-ad-spy", "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-spy/run-sync": { "post": { "operationId": "run-sync-deepmine-meta-ad-spy", "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": "🏢 Competitors", "type": "array", "description": "The advertisers to spy on: a Facebook page link (facebook.com/gymshark), a page id, an Ad Library link of the advertiser, or the page name exactly as it shows on its ads. One per line.", "items": { "type": "string" } }, "searchQueries": { "title": "🔍 Keywords or products", "type": "array", "description": "Find ads by keyword or product, as you'd type them in the Ad Library search box (e.g. posture corrector). One search per line.", "items": { "type": "string" } }, "adIds": { "title": "🆔 Ad IDs", "type": "array", "description": "Single ads: the Library ID the Ad Library shows on each ad, or the ad's link (facebook.com/ads/library/?id=...). Every country and status.", "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": "US" }, "maxAdsPerQuery": { "title": "💯 Max ads per competitor or search", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop each competitor, search or URL after this many ads. You pay per ad, so this caps the cost of each one. 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 }, "includeVariants": { "title": "🧬 Every variant of each creative", "type": "boolean", "description": "Meta groups ads that use the same creative and text, and its results often show one ad per group. Turn this on to also get the group's other ads (its variants: other versions, start dates, placements), each as its own ad row, which you pay for like any ad. They count toward Max ads.", "default": false }, "includeAdDetails": { "title": "📋 Advertiser and EU reach details", "type": "boolean", "description": "Also fetch each ad's public 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. Included in the ad price; each ad needs one more request, so runs are slower.", "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 competitor or search, reading up to 1,000 ads past Max ads to find them. You pay only for the new ads. Schedule the run (e.g. daily) to get each competitor's new ads as they launch. The first run returns the newest ads, up to Max ads.", "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 keywords 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 } } } } } } } } } }