{ "openapi": "3.0.1", "info": { "title": "Meta Ad Intelligence", "description": "Meta Ad Intelligence scrapes Facebook Ads Library to discover who is advertising in your niche, rank competitors by dominance score and share of voice, flag new entrants, and reveal top ad formats, CTAs, hooks, and creative trends for market research.", "version": "0.2", "x-build-id": "XchrOITjqfeUQQtzE" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/deepmine~meta-ad-intelligence/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-deepmine-meta-ad-intelligence", "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-intelligence/runs": { "post": { "operationId": "runs-sync-deepmine-meta-ad-intelligence", "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-intelligence/run-sync": { "post": { "operationId": "run-sync-deepmine-meta-ad-intelligence", "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": "🔎 Market keywords", "type": "array", "description": "Keywords, products or niches, as you'd type them in the Ad Library search box (e.g. running shoes). Each is one search; the tables rank who advertises for it. One per line.", "items": { "type": "string" } }, "advertisers": { "title": "🏢 Competitors", "type": "array", "description": "Advertisers to analyse: 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" } }, "country": { "title": "🌍 Country", "type": "string", "description": "Two-letter country code where the ads ran (US, GB, DE, ...), or ALL for every country. Each country is its own market: its tables and changes are kept apart.", "default": "US" }, "maxAdsPerQuery": { "title": "💯 Max ads per search", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop each keyword, competitor or URL after this many ads. You pay per ad, so this caps the cost of each one; the tables count these ads (most impressions first). 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 (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 search, reading up to 1,000 ads past Max ads to find them. You pay only for the new ads, and the tables then count only them. To track a market's changes, schedule the run without it: every run compares with the last one anyway.", "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" } }, "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" } }, "activeStatus": { "title": "Ad status", "enum": [ "active", "inactive", "all" ], "type": "string", "description": "Only active ads, only ads that stopped, or both. With both, the changes table also shows ads that stopped since the last run.", "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)." }, "rowLayout": { "title": "Row layout", "enum": [ "current", "earlier" ], "type": "string", "description": "Current: the rows described in the README. Earlier version's: each row starts with the earlier version's fields (rowType, query, adAgeDays, trendLabel, format as VIDEO, cta as SHOP_NOW, ...), then the current ones. Left empty (tasks, schedules and API calls made for the earlier version), an input with searchQueries, advertiserNames or maxAdsPerAdvertiser gets the earlier layout." }, "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 } } } } } } } } } }