{
  "openapi": "3.0.1",
  "info": {
    "title": "Meta Ad Library Winning Ads Finder & Creative Brief",
    "description": "Find any brand's winning Facebook & Instagram ads from the Meta Ad Library, tiered Proven Winner (30+ days), Rising or Testing, with a creative brief of hooks, angles, formats and CTAs. Flags new ads. Keyword search mode lists the brands advertising in a niche.",
    "version": "0.2",
    "x-build-id": "guDbqre2JndQx1zTL"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/kingly_contest_7cb~meta-ad-library-winning-ads/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-kingly_contest_7cb-meta-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/kingly_contest_7cb~meta-ad-library-winning-ads/runs": {
      "post": {
        "operationId": "runs-sync-kingly_contest_7cb-meta-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/kingly_contest_7cb~meta-ad-library-winning-ads/run-sync": {
      "post": {
        "operationId": "run-sync-kingly_contest_7cb-meta-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",
        "properties": {
          "mode": {
            "title": "Mode",
            "enum": [
              "brand",
              "keywordSearch"
            ],
            "type": "string",
            "description": "'Analyze one brand' (default) ranks a brand's ads and writes the creative brief. 'Keyword search (find advertisers)' searches the Ad Library for keywords and returns one row per unique advertiser (page), with website domain, active ad count and an Ad Library link. Keyword search charges only per ad processed (no brief).",
            "default": "brand"
          },
          "brand": {
            "title": "Brand",
            "type": "string",
            "description": "Required in 'Analyze one brand' mode. Facebook page URL (best, e.g. https://www.facebook.com/allbirds), a Meta Ad Library URL, or a plain brand name (keyword search, filtered to pages whose name matches)."
          },
          "searchTerms": {
            "title": "Search terms (keyword search mode)",
            "type": "array",
            "description": "Keyword search mode only. One Ad Library keyword search per term (all words, any order). Advertisers are de-duplicated by page ID across all terms.",
            "items": {
              "type": "string"
            }
          },
          "maxAdsPerTerm": {
            "title": "Max ads per term (keyword search mode)",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Keyword search mode only. Ads fetched per search term (sorted by impressions). This is your cost control: you are charged per ad processed, and the underlying scraper bills about $0.00075 per ad. Active ad counts per advertiser only cover the ads fetched, so they can be capped by this number.",
            "default": 100
          },
          "keywordActiveStatus": {
            "title": "Ad status (keyword search mode)",
            "enum": [
              "active",
              "all",
              "inactive"
            ],
            "type": "string",
            "description": "Keyword search mode only. Search active ads (default), all ads, or only inactive ads.",
            "default": "active"
          },
          "exactPhrase": {
            "title": "Exact phrase (keyword search mode)",
            "type": "boolean",
            "description": "Keyword search mode only. Match the exact phrase instead of all words in any order.",
            "default": false
          },
          "country": {
            "title": "Country",
            "type": "string",
            "description": "2-letter ISO country code the ads were shown in, or ALL.",
            "default": "US"
          },
          "activeStatus": {
            "title": "Ad status",
            "enum": [
              "all",
              "active",
              "inactive"
            ],
            "type": "string",
            "description": "Analyze all ads (recommended: stopped ads show what was cut), only active, or only inactive.",
            "default": "all"
          },
          "maxAds": {
            "title": "Max ads to analyze",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Upper limit of ad cards fetched from the Ad Library (sorted by impressions).",
            "default": 200
          },
          "rescopeToPage": {
            "title": "Re-scope name searches to the brand's page",
            "type": "boolean",
            "description": "When the brand is given as a name (or a page URL the scraper can't open), the Ad Library keyword search also returns other advertisers. If a page whose name matches is found, the Actor re-fetches only that page's ads (one extra scraper call). Turn off to keep the cheaper, noisier keyword-only result.",
            "default": true
          },
          "scoringConfig": {
            "title": "Winner scoring config",
            "type": "object",
            "description": "How winners are scored and tiered. Tiers: Proven Winner = running at least minDaysForWinner days (default 30, hard minimum); Rising = minDaysForRising-29 days (default 14) with at least minVariationsForRising variations (default 3); Testing = everything else. Score 0-100 ranks concepts inside each tier: days running carries the most weight (sqrt curve up to daysCap=180 days), longRunVariations = days x variations so many versions only count when the ad has also run long, small weights for variations alone and still-active, and reportedSpend only for ads where Meta discloses spend (political/social-issue ads); otherwise that weight is dropped, never estimated. See README. Concepts are Meta's own collation groups (collation_id); ads are never merged by similar copy or launch date.",
            "default": {
              "weights": {
                "daysRunning": 0.45,
                "longRunVariations": 0.3,
                "variationCount": 0.05,
                "isActive": 0.1,
                "reportedSpend": 0.1
              },
              "daysCap": 180,
              "daysExponent": 0.5,
              "variationCap": 20,
              "spendCapUsd": 100000,
              "minDaysForWinner": 30,
              "winnerScoreThreshold": 0,
              "minDaysForRising": 14,
              "minVariationsForRising": 3
            }
          },
          "briefTopN": {
            "title": "Concepts used for the brief",
            "minimum": 3,
            "maximum": 50,
            "type": "integer",
            "description": "Maximum number of top winners the creative brief is built from.",
            "default": 10
          },
          "outputMode": {
            "title": "Dataset rows",
            "enum": [
              "all",
              "winners"
            ],
            "type": "string",
            "description": "Output every ranked concept, or only winners.",
            "default": "all"
          },
          "monitoring": {
            "title": "Monitoring mode (flag new ads)",
            "type": "boolean",
            "description": "Remember which ads were seen per brand and flag ads/concepts that are new since the previous run. Schedule the Actor daily or weekly to get alerts.",
            "default": true
          },
          "monitorStoreName": {
            "title": "Monitoring store name",
            "type": "string",
            "description": "Named key-value store in your account that keeps the per-brand state. Use different names to keep separate watchlists.",
            "default": "winning-ads-monitor"
          },
          "dataSource": {
            "title": "Data source",
            "enum": [
              "curious_coder",
              "apify_official",
              "dataset"
            ],
            "type": "string",
            "description": "Where ads come from. Store scrapers are billed on their own pricing in addition to this Actor. 'dataset' re-analyzes ads you already scraped (no scraping cost).",
            "default": "curious_coder"
          },
          "sourceDatasetId": {
            "title": "Source dataset ID",
            "type": "string",
            "description": "Only for data source 'dataset': ID or name of a dataset produced by one of the supported scrapers."
          },
          "scraperMaxChargeUsd": {
            "title": "Scraper spending cap (USD)",
            "minimum": 0.001,
            "type": "number",
            "description": "Maximum the underlying scraper run may charge. Leave empty to derive it from max ads."
          },
          "llmProvider": {
            "title": "AI summary provider (optional)",
            "enum": [
              "none",
              "openai",
              "anthropic"
            ],
            "type": "string",
            "description": "Add an AI-written strategy summary to the brief using your own API key. Included in the creative-brief price; your LLM provider bills you directly for its tokens.",
            "default": "none"
          },
          "llmApiKey": {
            "title": "LLM API key",
            "type": "string",
            "description": "Your OpenAI or Anthropic API key. Stored encrypted; never written to output."
          },
          "llmModel": {
            "title": "LLM model",
            "type": "string",
            "description": "Optional model name override (defaults: gpt-4o-mini / claude-3-5-haiku-latest)."
          },
          "discoveryMaxAds": {
            "title": "Discovery ads (keyword fallback)",
            "minimum": 5,
            "maximum": 200,
            "type": "integer",
            "description": "When a brand name (or a page URL the scraper rejects) needs a keyword search to find the page ID, fetch only this many ads in that first pass before re-fetching the page's own ads. Keeps scraper cost down.",
            "default": 20
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}