{ "openapi": "3.0.1", "info": { "title": "Facebook Ad Library Winning Ads Finder: AI creative breakdown", "description": "First 25 ads free. Facebook Ad Library winning ads: collapses variants, drops dead, political and seen ads, scores each Facebook and Instagram creative by days running, adds an AI hook, angle and offer. Pay per qualified ad. Free demo on any plan; live search runs on your own Apify account.", "version": "0.3", "x-build-id": "B5cxu0JC5c3MVOZy0" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/rich_minds~fb-ad-library-winning-ads/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-rich_minds-fb-ad-library-winning-ads", "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/rich_minds~fb-ad-library-winning-ads/runs": { "post": { "operationId": "runs-sync-rich_minds-fb-ad-library-winning-ads", "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/rich_minds~fb-ad-library-winning-ads/run-sync": { "post": { "operationId": "run-sync-rich_minds-fb-ad-library-winning-ads", "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", "required": [ "sourceMode" ], "properties": { "sourceMode": { "title": "Where do the ads come from?", "enum": [ "actor", "dataset", "list" ], "type": "string", "description": "actor — search the Meta Ad Library live with curious_coder/facebook-ads-library-scraper on your account (≈ $0.00075 per ad scanned, billed by that Actor; needs an Apify plan that can run Store Actors — if yours cannot, the run stops at once and nothing is charged). dataset — qualify an existing dataset from that scraper or from apify/facebook-ads-scraper. list — Ad Library records you paste in. The form starts on the free demo (8 sample ads, nothing charged); an API call that names nothing to search ({}) runs the same demo.", "default": "actor" }, "searchTerms": { "title": "Search terms (what your competitors sell)", "type": "array", "description": "Keywords searched in the Meta Ad Library, one search per term — a product (posture corrector), a niche (dog harness) or a claim (vitamin c serum). Each term runs as an Ad Library keyword search in your country. The prefilled terms are the demo's — replace them with yours.", "items": { "type": "string" } }, "productBrief": { "title": "Your product / offer (for the AI)", "type": "string", "description": "Describe what you sell in one or two sentences. The AI scores how well each competitor ad's angle would transfer to your product (fit score) and rewrites its angle for your product — never copying their brand, claims or prices. Leave empty for the creative breakdown only." }, "minScore": { "title": "Minimum final score (0–100)", "minimum": 0, "maximum": 100, "type": "integer", "description": "The field that decides what you pay: ads whose final score (winner score, blended 60/40 with the AI fit score when you gave a product brief) is below this are discarded and not charged. 70+ = winners only.", "default": 40 }, "maxDiscoveryChargeUsd": { "title": "Max source spend (USD)", "minimum": 0.01, "maximum": 1000, "type": "number", "description": "Hard cap on what the source Actor run may charge your account in actor mode — $0.50 in the form and for an API or agent call that leaves it out, so a first real search can never cost more. Raise it for bigger searches.", "default": 0.5 }, "maxQualified": { "title": "Max qualified ads to output", "minimum": 1, "maximum": 10000, "type": "integer", "description": "The cap on what this Actor charges per run: at most this many qualified ads are delivered and billed, best first — the worst case is 100 × $0.012 = $1.20 with AI on ($0.30 with AI off), plus the source's own cap above (Max source spend). Your first 25 ads are free.", "default": 100 }, "enableAi": { "title": "AI creative breakdown", "type": "boolean", "description": "The AI writes the hook, angle, offer, CTA, audience and emotional trigger with verbatim evidence quotes, a fit score against your product brief and a rewrite of the angle for your product. On = $0.012 per qualified ad + AI tokens; off = $0.003 (rule-based winner score, offer and hook only).", "default": true }, "maxAdsToScan": { "title": "Max ads to scan (source)", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Total ads the source scrapes across all searches — what it bills on your account (≈ $0.00075 each, so 150 ≈ $0.11). Variants, dead and filtered ads among them are never charged here.", "default": 150 }, "competitorPages": { "title": "Competitor Facebook pages", "type": "array", "description": "Facebook page URLs (or page names) of the competitors to watch — every ad they run is scanned, sorted by impressions. Use it for weekly competitor monitoring next to, or instead of, search terms.", "items": { "type": "string" } }, "adLibraryUrls": { "title": "Ad Library URLs", "type": "array", "description": "Any Meta Ad Library URL you already use (a search with your own filters, a page's ad list) — passed to the source as is.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "ALL", "US", "GB", "CA", "AU", "DE", "FR", "ES", "IT", "NL", "BR", "MX", "IN", "IE", "NZ", "AF", "AL", "DZ", "AD", "AO", "AG", "AR", "AM", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BT", "BO", "BA", "BW", "BN", "BG", "BF", "BI", "KH", "CM", "CV", "CF", "TD", "CL", "CN", "CO", "KM", "CG", "CD", "CR", "CI", "HR", "CY", "CZ", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FJ", "FI", "GA", "GM", "GE", "GH", "GR", "GD", "GT", "GN", "GW", "GY", "HT", "HN", "HK", "HU", "IS", "ID", "IQ", "IL", "JM", "JP", "JO", "KZ", "KE", "KI", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MR", "MU", "FM", "MD", "MC", "MN", "ME", "MA", "MZ", "MM", "NA", "NR", "NP", "NI", "NE", "NG", "MK", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PL", "PT", "PR", "QA", "RO", "RU", "RW", "KN", "LC", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SK", "SI", "SB", "SO", "ZA", "KR", "SS", "LK", "SR", "SE", "CH", "TW", "TJ", "TZ", "TH", "TL", "TG", "TO", "TT", "TN", "TR", "TM", "TV", "UG", "UA", "AE", "UY", "UZ", "VU", "VE", "VN", "YE", "ZM", "ZW" ], "type": "string", "description": "The Ad Library country searched — pick from the list (All countries searches every country). Over the API send the two-letter code (US, GB, DE …) or ALL; UK, USA and country names are mapped for you, anything else stops the run at once with the valid codes.", "default": "US" }, "activeStatus": { "title": "Ad status", "enum": [ "active", "all", "inactive" ], "type": "string", "description": "Active = ads still running today (the winners); All also includes ads that stopped; Inactive = only stopped ads. Used in the search and as a free filter.", "default": "active" }, "mediaType": { "title": "Media type", "enum": [ "all", "image", "video" ], "type": "string", "description": "Only image or only video creatives — in the search and as a free filter.", "default": "all" }, "period": { "title": "Page ads from the last …", "enum": [ "all", "last24h", "last7d", "last14d", "last30d" ], "type": "string", "description": "For competitor pages: only ads seen in this window.", "default": "all" }, "maxAdsPerSearch": { "title": "Max ads per search / page", "minimum": 1, "maximum": 5000, "type": "integer", "description": "The most ads the source takes from one search term or page, so one broad term cannot use the whole scan budget.", "default": 50 }, "minWinnerScore": { "title": "Minimum winner score (0–100)", "minimum": 0, "maximum": 100, "type": "integer", "description": "The free rule bar applied before any AI token is spent: days running (up to 40 points), still active (15), variants (20), 2+ placements (10), impressions when Meta publishes them (15). 70+ = winner, 40–69 = promising.", "default": 40 }, "minDaysRunning": { "title": "Minimum days running", "minimum": 0, "maximum": 3650, "type": "integer", "description": "Drop ads younger than this — an ad that has run for weeks is the only public sign that it pays for itself.", "default": 7 }, "minVariants": { "title": "Minimum variants", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Only creatives the advertiser runs in at least this many variants (Meta's collation count — a scaled creative has many).", "default": 1 }, "platforms": { "title": "Placements (Facebook, Instagram …)", "type": "array", "description": "Keep ads shown on at least one of these placements. Empty = any.", "items": { "type": "string", "enum": [ "facebook", "instagram", "messenger", "audience_network", "threads" ], "enumTitles": [ "Facebook", "Instagram", "Messenger", "Audience Network", "Threads" ] } }, "landingDomainIncludes": { "title": "Landing domain must be", "type": "array", "description": "Keep only ads whose landing page is on one of these domains (e.g. myshopify.com, amazon.com).", "items": { "type": "string" } }, "landingDomainExcludes": { "title": "Landing domains to skip", "type": "array", "description": "Drop ads that link to these domains (marketplaces, your own site).", "items": { "type": "string" } }, "excludeAdvertisers": { "title": "Advertisers to skip", "type": "array", "description": "Your own brand, your clients or anyone you do not want in the list — a page name (part of it), page id or landing domain.", "items": { "type": "string" } }, "includePoliticalAds": { "title": "Include political / issue ads", "type": "boolean", "description": "Off by default: political and social-issue ads are dropped before any charge.", "default": false }, "adLanguage": { "title": "Ad text language", "enum": [ "any", "en", "de", "fr", "es", "it", "pt", "nl" ], "type": "string", "description": "Keep only ads whose copy is in this language (a stop-word guess; ads it cannot tell are kept).", "default": "any" }, "targetFlags": { "title": "Target flags (any of)", "type": "array", "description": "Only deliver ads that have at least one of these flags, e.g. free_shipping, has_discount, long_running, video_creative (freeShipping works too). Leave empty to keep everything; an unknown name stops the run at once with the list of valid ones.", "items": { "type": "string" } }, "suppressionList": { "title": "Exclude list (ids / URLs)", "type": "array", "description": "Ad archive ids, Ad Library URLs or dedupe keys to never output. Skipped before any processing and never charged.", "items": { "type": "string" } }, "llmProvider": { "title": "AI model access", "enum": [ "apify", "byok" ], "type": "string", "description": "Apify (no keys) — the AI runs through Apify's built-in OpenRouter proxy; tokens are billed to your Apify account at OpenRouter's rates. My own key — use your OpenAI / Anthropic / Gemini / Groq key instead; a free-tier key is slower (2 calls at a time, one after a rate limit — measured up to 27 s per ad, so the worst case per 100 qualified ads is ≈ 45 min: 200 ads in the AI pool, 2 at a time). The AI stops before the run's timeout and the rest keep their rule score.", "default": "apify" }, "llmModel": { "title": "AI model", "type": "string", "description": "Leave empty for the default (anthropic/claude-haiku-4.5). Apify mode takes an OpenRouter slug such as openai/gpt-4.1-mini; own-key mode takes provider:model, e.g. anthropic:claude-haiku-4-5-20251001." }, "llmApiKey": { "title": "Your API key (own-key mode only)", "type": "string", "description": "Required when AI model access is My own API key. Stored encrypted by Apify, never logged." }, "outputLanguage": { "title": "AI output language", "type": "string", "description": "Language of the creative breakdown and of the rewrite for your product (quotes stay in the ad's language).", "default": "English" }, "aiCandidateMultiplier": { "title": "AI candidate pool (× max qualified)", "minimum": 1, "maximum": 5, "type": "integer", "description": "How many of the best rule-scored ads get the AI pass, as a multiple of Max qualified. Higher = more thorough, slower, more tokens.", "default": 2 }, "notifyEmail": { "title": "E-mail me the new ads (optional)", "type": "string", "description": "After every run with at least one new ad, the run's digest (how many are new, the top 10 with links and hooks) is e-mailed here through Apify's send-mail Actor. Schedule the run weekly and the new winning ads come to your inbox — no Slack or Zapier needed. Never sent for the free demo." }, "slackWebhookUrl": { "title": "Post the digest to Slack (optional)", "type": "string", "description": "A Slack incoming-webhook URL (https://hooks.slack.com/services/…). After every run with something new, the digest — new ads with hook and days running, change alerts, competitors to watch and the report link — is posted to that channel as a readable message, not raw JSON. Never posted for the free demo; a refused post is one log line, the run still succeeds." }, "changeAlerts": { "title": "Change alerts on ads you already have", "type": "boolean", "description": "For a scheduled monitor: every run also re-checks the ads you received before and adds one rowType: alert row when a competitor stopped an ad (a loser killed) or an ad passed 30 / 60 / 90 days (a winner confirmed) — in the dataset, the e-mail digest and the webhook. $0.003 per alert (ad-alert), never on the free demo. To see an ad stop, the search also fetches stopped ads (inside Max ads to scan); new rows stay active-only.", "default": false }, "advertiserReports": { "title": "Competitor report rows", "type": "boolean", "description": "Adds one rowType: advertiser row per top advertiser of the run (up to 10): active ads, new this run, stopped, ads running 30+ days, average days running, share of voice, top angles and offers, best ad — the per-competitor summary an agency forwards. $0.02 per advertiser row (advertiser-report), never on the free demo (which shows one sample row). A weekly monitor with nothing new still gets its reports.", "default": false }, "enrichLandingPages": { "title": "Read each ad's landing page", "type": "boolean", "description": "Opens the landing page of every qualified ad and adds landingPage: store platform (Shopify, WooCommerce …), product title, price, rating and reviews count — what the page states itself, nothing guessed. $0.004 per page that yields a store or a product (landing-enriched); unreachable pages and your free ads cost nothing. Adds a few seconds per 5 pages; stops before the run's timeout.", "default": false }, "webhookUrl": { "title": "Webhook URL (optional)", "type": "string", "description": "Qualified ads are POSTed here as JSON (Zapier, Make, n8n, your CRM). For a Slack channel use Post the digest to Slack above — a Slack webhook here would receive raw JSON." }, "webhookHeaders": { "title": "Webhook headers (optional)", "type": "object", "description": "Extra HTTP headers for the webhook, e.g. {\"Authorization\": \"Bearer …\"}." }, "webhookBatchSize": { "title": "Webhook batch size", "minimum": 1, "maximum": 500, "type": "integer", "description": "1 = one POST per ad the moment it is ready. Higher = one POST per N ads.", "default": 1 }, "onlyNewAds": { "title": "Only ads new since the last run", "type": "boolean", "description": "Remembers every ad (and each of its variants) you received, in a named key-value store on your account, and skips it in later runs — a weekly schedule delivers and charges only new ads. Off: earlier ads come again, marked isNewSinceLastRun: false.", "default": true }, "dedupeStoreName": { "title": "Dedupe store name", "type": "string", "description": "Key-value store used for the cross-run memory. Left at the default, the memory is kept per search (terms, pages, URLs, country and product brief): each client's monitor keeps its own list. Type your own name to share one memory across searches.", "default": "fb-ad-library-winning-ads-seen" }, "datasetId": { "title": "Dataset", "type": "string", "description": "Only for dataset mode: a dataset of curious_coder/facebook-ads-library-scraper or apify/facebook-ads-scraper. Pick it so the Actor is granted read access to it." }, "itemsList": { "title": "Ad Library records to process", "type": "array", "description": "Only for list mode. JSON array of Meta Ad Library records in either scraper's shape (ad_archive_id + snapshot, or adArchiveID + snapshot). Records without an archive id are skipped and never charged." }, "discoveryActorId": { "title": "Source Actor (advanced)", "type": "string", "description": "Actor used in actor mode. Any Actor whose output has the Meta Ad Library fields listed in the README works.", "default": "curious_coder/facebook-ads-library-scraper" }, "discoveryInput": { "title": "Source Actor input overrides", "type": "object", "description": "Only for actor mode. Keys merged over the input this Actor builds for the source (e.g. {\"scrapeAdDetails\": true}). See the source Actor's input schema." }, "maxToProcess": { "title": "Max candidates to process", "minimum": 1, "maximum": 20000, "type": "integer", "description": "Upper bound on how many ads are scored in one run (controls run time). Default = 3 × max qualified." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Not used by this Actor itself (the source Actor brings its own proxy); kept for compatibility." } } }, "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 } } } } } } } } } }