{
  "openapi": "3.0.1",
  "info": {
    "title": "Winning Ads Finder: Facebook Ad Library Longevity Scorer",
    "description": "Scores Facebook and Instagram Ad Library ads (or Google Ads Transparency rows, a CSV or Sheet) by days running, copies and live status, and ranks the proven winners first. No scraping or login. Charged per ad scored. Agent-ready: MCP, x402.",
    "version": "0.1",
    "x-build-id": "PoI99Dpq8DfX8FOgs"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/nerolabs~winning-ads-finder/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-nerolabs-winning-ads-finder",
        "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/nerolabs~winning-ads-finder/runs": {
      "post": {
        "operationId": "runs-sync-nerolabs-winning-ads-finder",
        "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/nerolabs~winning-ads-finder/run-sync": {
      "post": {
        "operationId": "run-sync-nerolabs-winning-ads-finder",
        "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": {
          "datasetIds": {
            "title": "Datasets",
            "type": "array",
            "description": "One or more ad scraper datasets: Facebook and Instagram Ad Library scrapers (curious_coder/facebook-ads-library-scraper, apify/facebook-ads-scraper, memo23, whoareyouanas and look-alikes) or Google Ads Transparency scrapers. A rival's page, a keyword search or a whole niche. In a scraper's Integrations tab, set this to {{resource.defaultDatasetId}}."
          },
          "fileUrl": {
            "title": "File or Google Sheet URL",
            "type": "string",
            "description": "A public link to a CSV, Excel, JSON or JSON Lines file: Ad Library scraper rows, or your own sheet with an advertiser and an ad start date column (plus end date, active, copies and landing page if you have them). Google Sheets share links work (set 'Anyone with the link can view')."
          },
          "fileFormat": {
            "title": "File format",
            "enum": [
              "auto",
              "csv",
              "tsv",
              "json",
              "jsonl",
              "xlsx"
            ],
            "type": "string",
            "description": "Leave on 'Detect automatically' unless the link has no file extension.",
            "default": "auto"
          },
          "sheetName": {
            "title": "Excel sheet name",
            "type": "string",
            "description": "Which sheet to read from an Excel workbook. Defaults to the first sheet."
          },
          "data": {
            "title": "Ad rows",
            "type": "array",
            "description": "Rows as JSON objects, for a quick run or an AI agent call, e.g. [{\"advertiser\": \"Acme\", \"adId\": \"123\", \"startDate\": \"2026-06-01\", \"isActive\": true, \"copies\": 4, \"landingUrl\": \"https://acme.com/offer\"}]. Ad Library scraper rows can be passed as they are."
          },
          "minDaysRunning": {
            "title": "Only ads running at least (days)",
            "minimum": 0,
            "maximum": 3650,
            "type": "integer",
            "description": "Leave out ads that ran fewer days than this (not charged). 0 = keep every ad. 30 is a common 'winning ad' line.",
            "default": 0
          },
          "onlyLive": {
            "title": "Only ads still live",
            "type": "boolean",
            "description": "Keep only ads that are still running on the day the rows were scraped (not charged for the rest).",
            "default": false
          },
          "tiers": {
            "title": "Only these tiers",
            "type": "array",
            "description": "Keep only ads in these tiers (empty = all). Proven winner: live 30+ days or ran 90+. Scaling: live with 3+ copies. Promising: live 14+ days. Testing: live under 14 days. Stopped early: off within 14 days. Ran a while: ran 14 to 89 days, then stopped.",
            "items": {
              "type": "string",
              "enum": [
                "proven_winner",
                "scaling",
                "promising",
                "testing",
                "stopped_early",
                "ran_a_while"
              ],
              "enumTitles": [
                "Proven winner",
                "Scaling",
                "Promising",
                "Testing",
                "Stopped early",
                "Ran a while"
              ]
            }
          },
          "topPerAdvertiser": {
            "title": "Top ads per advertiser",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Keep only each advertiser's best N ads by winner score (0 = all). Handy for a niche scan with many advertisers.",
            "default": 0
          },
          "includeAdvertiserSummary": {
            "title": "Add a summary row per advertiser",
            "type": "boolean",
            "description": "Free extra rows (type 'advertiser_summary'): ads, live ads, proven winners, median days running, new ads in the last 7 and 30 days (how fast they test), share stopped early, top ad and top landing domains.",
            "default": true
          },
          "asOfDate": {
            "title": "Scrape date (optional)",
            "type": "string",
            "description": "The date the rows were scraped, e.g. 2026-11-01, used to count days for live ads. Leave empty to work it out from the rows (the newest end date on a live ad)."
          },
          "exportFormats": {
            "title": "Also save as a file",
            "type": "array",
            "description": "Also save the results as CSV or Excel in the run's key-value store (charged once per file).",
            "items": {
              "type": "string",
              "enum": [
                "csv",
                "xlsx"
              ],
              "enumTitles": [
                "CSV",
                "Excel (xlsx)"
              ]
            }
          },
          "outputDatasetName": {
            "title": "Also append to a named dataset",
            "type": "string",
            "description": "Name of a dataset to append the results to, to track a rival's ads week by week."
          },
          "maxItems": {
            "title": "Max input rows",
            "minimum": 1,
            "maximum": 200000,
            "type": "integer",
            "description": "Stop reading after this many input rows.",
            "default": 200000
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}