{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Creative Center Top Ads & Hook Analyzer Pro",
    "description": "Extract winning TikTok Top Ads from TikTok Creative Center with 3-second hook retention, peak CTR seconds, landing pages, direct HD MP4 links, B2B Brand Lead-Gen mode & AI Hook Prompts — no login cookies, $0 proxy cost, $1.50/1k ads all-inclusive.",
    "version": "1.0",
    "x-build-id": "hMDH8mLuM9mtu2thO"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/voxatools~tiktok-creative-center-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-voxatools-tiktok-creative-center-scraper",
        "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/voxatools~tiktok-creative-center-scraper/runs": {
      "post": {
        "operationId": "runs-sync-voxatools-tiktok-creative-center-scraper",
        "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/voxatools~tiktok-creative-center-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-voxatools-tiktok-creative-center-scraper",
        "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": {
          "resultType": {
            "title": "1. Output Mode (Video Ads Spy vs. B2B Brand & Advertiser Lead-Gen)",
            "enum": [
              "ads",
              "advertisers",
              "brands"
            ],
            "type": "string",
            "description": "Select 'ads' (default) to extract individual winning TikTok video ads with 3-second hook retention, CTR percentile, landing pages, direct MP4 links, and AI script prompts ($1.50/1k all-inclusive). Select 'advertisers' (or 'brands') to aggregate results into 1 B2B lead summary row per brand/domain ($2.50/1k brands).",
            "default": "ads"
          },
          "keywords": {
            "title": "2. Target Niche Keywords, Sub-Industries, Brand Names, or Ad IDs",
            "type": "array",
            "description": "List of niche keywords, product categories, brand names, or 19-digit TikTok material IDs to analyze (e.g., 'skincare', 'beauty', 'gaming', 'fitness', 'supplements', 'fashion', 'ecommerce'). Automatically maps to all 258 official TikTok industries & sub-industries.",
            "items": {
              "type": "string"
            }
          },
          "keyword": {
            "title": "3. Single Keyword / Niche Query (Optional Alias for API/MCP)",
            "type": "string",
            "description": "Optional single niche keyword, brand name, or 19-digit TikTok Ad ID (e.g., 'skincare') merged automatically with 'keywords' for convenient single-query API and MCP calls."
          },
          "country": {
            "title": "4. Target Country / Ad Market",
            "enum": [
              "ALL",
              "US",
              "GB",
              "CA",
              "AU",
              "DE",
              "FR",
              "SG",
              "VN",
              "JP",
              "KR",
              "ID",
              "TH",
              "MY",
              "PH",
              "BR",
              "MX",
              "AE",
              "SA",
              "ES",
              "IT",
              "NL",
              "PL",
              "SE"
            ],
            "type": "string",
            "description": "Filter TikTok Top Ads served in a specific country (ISO-2 country code such as US, GB, CA, AU, DE, FR, VN, SG, ID, TH, JP, KR, BR) or select 'ALL' for global campaigns.",
            "default": "US"
          },
          "industry": {
            "title": "5. Official TikTok Industry / Sub-Industry Filter (Optional)",
            "type": "string",
            "description": "Optional industry name or 11-digit TikTok industry code (e.g., 'Beauty & Personal Care', 'Skincare', 'E-Commerce', 'Games', 'Health', or '14000000000'). Leave empty to auto-resolve from your keywords.",
            "default": ""
          },
          "objective": {
            "title": "6. Campaign Marketing Objective Filter",
            "enum": [
              "ALL",
              "CONVERSIONS",
              "PRODUCT_SALES",
              "LEAD_GENERATION",
              "TRAFFIC",
              "APP_INSTALLS",
              "VIDEO_VIEWS",
              "REACH"
            ],
            "type": "string",
            "description": "Filter ads by their TikTok Ad Manager campaign objective: All Objectives, Conversions, Product Sales (TikTok Shop), Lead Generation, Traffic, App Installs, Video Views, or Reach.",
            "default": "ALL"
          },
          "period": {
            "title": "7. Time Period Window (Last 7, 30, or 180 Days)",
            "enum": [
              "7",
              "30",
              "180"
            ],
            "type": "string",
            "description": "Timeframe for TikTok Creative Center performance metrics: '7' (Last 7 days breakout trends), '30' (Last 30 days proven winners), or '180' (Last 180 days evergreen scaling ads).",
            "default": "30"
          },
          "orderBy": {
            "title": "8. Primary Ranking & Sort Metric",
            "enum": [
              "for_you",
              "ctr",
              "like",
              "play_2s_rate",
              "play_6s_rate"
            ],
            "type": "string",
            "description": "Primary metric used to rank top ads: 'for_you' (TikTok Relevance Score), 'ctr' (Highest Click-Through Rate), 'like' (Most Likes), 'play_2s_rate' (2-Second Hook Rate), or 'play_6s_rate' (6-Second Hold Rate).",
            "default": "ctr"
          },
          "adLanguage": {
            "title": "9. Ad Spoken / Caption Language (Optional)",
            "type": "string",
            "description": "Optional ISO language code filter for the video ad's spoken audio or captions (e.g., 'en', 'es', 'vi', 'ja', 'de', 'fr', 'pt'). Leave empty for all languages.",
            "default": ""
          },
          "maxResults": {
            "title": "10. Max Ads per Keyword / Niche Query",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum number of unique TikTok ads to extract per keyword or industry query (supports breaking past the 20-video public limit up to 200+ unique ads per query without cookies).",
            "default": 25
          },
          "includeHookRetention": {
            "title": "11. 🪝 Extract 3-Second Hook Retention & Peak CTR Second (Included Free in Base Tier)",
            "type": "boolean",
            "description": "When enabled (default true), automatically computes 3-second hook retention (hookRetention3s), 2s/6s hold rates, peak click-through second (hookPeakSecond), and steepest viewer drop-off second (hookDropoffSecond) at $0 extra add-on cost.",
            "default": true
          },
          "onlyWinners": {
            "title": "12. 🏆 Only Viral Conversion & Proven Hook Winners",
            "type": "boolean",
            "description": "When enabled, filters out testing creatives and only outputs top-tier ads classified as '🏆 VIRAL_CONVERSION_WINNER' or '🔥 PROVEN_HOOK_WINNER' based on CTR percentile and hook velocity.",
            "default": false
          },
          "deduplicateSparkClones": {
            "title": "13. 📈 Deduplicate Spark Ad & Campaign Clones (Zero Double-Charging)",
            "type": "boolean",
            "description": "When enabled (recommended), merges duplicate ads running the same video or landing page across multiple ad groups into 1 unique record while outputting 'campaignScaleCount' and 'clonedMaterialIds'.",
            "default": true
          },
          "includeDetails": {
            "title": "14. 📊 Deep Second-by-Second Keyframe Curves, 5 Industry Percentiles & Similar Ads Add-On (+$2.50 / 1,000 ads)",
            "type": "boolean",
            "description": "Note: 3s Hook Retention, Peak CTR Second, Landing Pages & MP4 URLs are ALREADY included FREE in the base tier! Enable this only when you need all 5 full second-by-second keyframe arrays, all 5 industry percentile benchmarks, and up to 6 recommended similar winning ads.",
            "default": false
          },
          "downloadAssets": {
            "title": "15. 💾 Download & Archive Permanent MP4 Video Assets to Cloud Storage (+$1.00 / 1,000 files)",
            "type": "boolean",
            "description": "Because TikTok CDN video links (tiktokcdn.com) contain 'x-expires' signatures that expire after a few hours, enable 'downloadAssets' to save permanent .mp4 video files into your Apify Key-Value Store ('savedAssetUrl').",
            "default": false
          },
          "downloadPreviews": {
            "title": "16. 🖼️ Download & Archive Permanent Cover Thumbnail JPGs to Cloud Storage (Optional)",
            "type": "boolean",
            "description": "When enabled, downloads and archives permanent high-resolution cover thumbnail images (.jpg) into your Apify Key-Value Store ('savedPreviewUrl') so thumbnails never expire inside Notion or Airtable.",
            "default": false
          },
          "maxAssetSizeKb": {
            "title": "17. Max Downloaded Video / Image Size Limit (KB)",
            "minimum": 100,
            "maximum": 102400,
            "type": "integer",
            "description": "Maximum allowed file size in Kilobytes (KB) per downloaded MP4 video or JPG cover when 'downloadAssets' or 'downloadPreviews' is enabled (Default: 20480 KB = 20 MB).",
            "default": 20480
          },
          "onlyNewAds": {
            "title": "18. 📡 Scheduled Delta Radar: Only Output Newly Discovered Winning Ads",
            "type": "boolean",
            "description": "When enabled on scheduled daily or weekly runs, remembers previously seen adIds in a persistent Key-Value Store ('monitorStoreName') and only outputs and bills for brand-new winning ads ($0.00 cost when 0 new ads appear).",
            "default": false
          },
          "monitorStoreName": {
            "title": "19. Monitor Key-Value Store Name",
            "type": "string",
            "description": "Named Apify Key-Value Store used to persist seen ad material IDs across scheduled runs when 'onlyNewAds' is enabled.",
            "default": "tiktok-creative-center-monitor"
          },
          "proxyConfiguration": {
            "title": "20. Proxy Configuration (Optional — $0 Direct Engine Works by Default)",
            "type": "object",
            "description": "Our Zero-Browser engine runs directly at <400ms latency with $0 proxy cost. Optional Apify Proxy configuration is available as a fallback for high-volume bulk runs."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}