{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Ads Scraper — Creative Center Top Ads",
    "description": "Scrape TikTok Creative Center Top Ads: video URLs, brand, likes, CTR rank, budget level, objective & industry. Global (up to ~400 ads per industry) or 28 markets. Up to 2,000 ads per run. No login.",
    "version": "1.0",
    "x-build-id": "69zmzsyKxaLH5Y8a5"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~tiktok-ads-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-tiktok-ads-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/khadinakbar~tiktok-ads-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-tiktok-ads-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/khadinakbar~tiktok-ads-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-tiktok-ads-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": {
          "country": {
            "title": "Country",
            "enum": [
              "",
              "US",
              "GB",
              "CA",
              "AU",
              "DE",
              "FR",
              "IT",
              "ES",
              "NL",
              "SE",
              "RO",
              "TR",
              "SA",
              "AE",
              "ZA",
              "JP",
              "KR",
              "ID",
              "TH",
              "VN",
              "MY",
              "PH",
              "SG",
              "PK",
              "BR",
              "MX",
              "AR",
              "CO"
            ],
            "type": "string",
            "description": "Market to pull Top Ads for. \"Global\" searches all markets, supports every filter (objective, Likes band, keyword) and returns up to ~400 ads per industry. A single country returns TikTok's public first page: about 20 ads per industry. To collect more for countries, add several industries or markets below.",
            "default": "US"
          },
          "countries": {
            "title": "Countries (several markets in one run)",
            "type": "array",
            "description": "Optional. Several markets in one run: two-letter codes such as US, GB, DE, or GLOBAL. When set, this replaces \"Country\". Each market × industry pair is collected separately and duplicates are removed. Max 30 pairs per run.",
            "items": {
              "type": "string"
            }
          },
          "industry": {
            "title": "Industry",
            "enum": [
              "All Industries",
              "Apparel & Accessories",
              "Apps",
              "Appliances",
              "Baby, Kids & Maternity",
              "Beauty & Personal Care",
              "Business Services",
              "E-Commerce (Non-app)",
              "Education",
              "Financial Services",
              "Food & Beverage",
              "Games",
              "Health",
              "Home Improvement",
              "Household Products",
              "Life Services",
              "News & Entertainment",
              "Pets",
              "Sports & Outdoor",
              "Tech & Electronics",
              "Travel",
              "Vehicle & Transportation",
              "Gaming",
              "E-commerce & Shopping",
              "Health & Fitness",
              "Entertainment",
              "Sports & Outdoors",
              "Finance",
              "Fashion & Apparel",
              "Technology",
              "Home & Décor",
              "Parenting & Kids",
              "Media & Entertainment",
              "News & Information",
              "Music"
            ],
            "type": "string",
            "description": "TikTok advertiser industry. \"All Industries\" returns cross-industry top performers. Old names from earlier versions (for example \"Gaming\") still work.",
            "default": "All Industries"
          },
          "industries": {
            "title": "Industries (several in one run)",
            "type": "array",
            "description": "Optional. Several industries by name (for example \"Games\", \"Beauty & Personal Care\") or by TikTok sub-industry ID (for example \"14105000000\" for Aesthetic Medicine). When set, this replaces \"Industry\". Each industry adds its own ads: up to ~400 on Global, about 20 per country.",
            "items": {
              "type": "string"
            }
          },
          "period": {
            "title": "Time Period",
            "enum": [
              "7",
              "30",
              "180"
            ],
            "type": "string",
            "description": "TikTok's ranking window: last 7, 30 or 180 days. This is not the dates the ads ran.",
            "default": "7"
          },
          "objective": {
            "title": "Campaign Objective",
            "enum": [
              "All Objectives",
              "Traffic",
              "App Installs",
              "Conversions",
              "Video Views",
              "Reach",
              "Lead Generation",
              "Product Sales",
              "App Promotion",
              "App Install"
            ],
            "type": "string",
            "description": "Keep only ads with this campaign objective. On Global, TikTok filters before paging, so you get many matches. On a country, ads are filtered after loading TikTok's first page.",
            "default": "All Objectives"
          },
          "likesPercentile": {
            "title": "Likes band (Global only)",
            "enum": [
              "All",
              "Top 1-20%",
              "Top 21-40%",
              "Top 41-60%",
              "Top 61-80%",
              "Top 81-100%"
            ],
            "type": "string",
            "description": "Keep only ads in this likes performance band, as TikTok ranks them (Top 1-20% = most liked). Works with Country = Global.",
            "default": "All"
          },
          "keyword": {
            "title": "Keyword",
            "type": "string",
            "description": "Optional search word, for example \"skincare\" or \"black friday\". On Global, TikTok searches the ads. On a country, ads whose title or brand contains the word are kept.",
            "default": ""
          },
          "orderBy": {
            "title": "Sort Order",
            "enum": [
              "For You",
              "Likes",
              "CTR",
              "Budget",
              "Cost"
            ],
            "type": "string",
            "description": "\"For You\" keeps TikTok's own ranking. \"Likes\" puts the most-liked ads first, \"CTR\" the best click-through rank first, \"Budget\" the highest budget level first. Sorting is applied to all ads collected for your filters.",
            "default": "For You"
          },
          "maxResults": {
            "title": "Max Ads to Return",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "How many ads to save (1-2,000). Global returns up to ~400 ads per industry; a single country about 20 per industry. Add industries or markets to reach larger numbers. If TikTok has fewer ads, the run saves what exists, finishes as PARTIAL and explains why in OUTPUT. Each saved ad is billed as one result.",
            "default": 50
          },
          "responseFormat": {
            "title": "Response Format",
            "enum": [
              "detailed",
              "concise"
            ],
            "type": "string",
            "description": "\"concise\" returns 18 core fields (good for AI agents and swipe files). \"detailed\" adds video quality URLs, duration, size, raw CTR and budget values, industry and objective codes and source details.",
            "default": "detailed"
          },
          "adFormat": {
            "title": "Ad Format (not available)",
            "enum": [
              "All Formats",
              "Spark Ads",
              "Non-Spark Ads",
              "Collection Ads"
            ],
            "type": "string",
            "description": "TikTok does not apply an ad-format filter to public Top Ads data. Keep \"All Formats\". Other values stop the run with a clear message instead of returning unfiltered ads.",
            "default": "All Formats"
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration",
            "type": "object",
            "description": "Used for country searches, which load the public Creative Center page. Residential Apify Proxy is the default and works best. Global searches do not use it.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}