{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Trending Creator Insights Scraper With Per-Video Stats",
    "description": "TikTok Trending Creator Scraper extracts data on trending creators from TikTok. Collect usernames, profile links, follower counts, video views, and engagement metrics to discover rising influencers, track trends, and identify collaboration or marketing opportunities in your niche.",
    "version": "0.1",
    "x-build-id": "6SZ3WZ3Yv2jPBYLQs"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/simpleapi~tiktok-trending-creator-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-simpleapi-tiktok-trending-creator-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/simpleapi~tiktok-trending-creator-scraper/runs": {
      "post": {
        "operationId": "runs-sync-simpleapi-tiktok-trending-creator-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/simpleapi~tiktok-trending-creator-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-simpleapi-tiktok-trending-creator-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",
        "required": [
          "countryCode",
          "sortBy"
        ],
        "properties": {
          "countryCode": {
            "title": "🌍 Primary Market",
            "enum": [
              "AU",
              "BR",
              "CA",
              "EG",
              "FR",
              "DE",
              "ID",
              "IL",
              "IT",
              "JP",
              "MY",
              "PH",
              "RU",
              "SA",
              "SG",
              "KR",
              "ES",
              "TW",
              "TH",
              "TR",
              "AE",
              "GB",
              "US",
              "VN",
              "AR",
              "CO",
              "MX",
              "ZA"
            ],
            "type": "string",
            "description": "Country whose TikTok trending board is read. Note: this is the market the creator trended in — TikTok does not publish the creator's own country on this surface.",
            "default": "US"
          },
          "extraCountryCodes": {
            "title": "➕ Extra Markets",
            "type": "array",
            "description": "Optional additional ISO-2 country codes to sweep in the same run (for example US, GB, MX). Each extra market costs one more board request and adds up to 9 more creators.",
            "items": {
              "type": "string"
            }
          },
          "trendPeriodDays": {
            "title": "🗓️ Trend Window",
            "enum": [
              "7",
              "30",
              "90"
            ],
            "type": "string",
            "description": "How far back the trending board looks. TikTok publishes exactly three windows.",
            "default": "7"
          },
          "sortBy": {
            "title": "📊 Order Creators By",
            "enum": [
              "follower",
              "engagement",
              "popularity"
            ],
            "type": "string",
            "description": "Applied client-side after scraping (TikTok exposes no sort parameter). Follower = board follower count. Engagement = average per-video engagement rate. Popularity = total plays across the measured videos.",
            "default": "follower"
          },
          "followerCount": {
            "title": "👥 Follower Bucket",
            "enum": [
              "10k-100k",
              "100k-1m",
              "1m-10m",
              ">10m"
            ],
            "type": "string",
            "description": "Client-side filter on the board follower count. Leave empty for no filter. Takes priority over 'Follower Bucket (extended)' whenever it is set."
          },
          "followerRange": {
            "title": "👥 Follower Bucket (extended)",
            "enum": [
              "any",
              "under-10k",
              "10k-100k",
              "100k-1m",
              "1m-10m",
              ">10m"
            ],
            "type": "string",
            "description": "Same filter with two extra options. Only used when 'Follower Bucket' above is left empty."
          },
          "maxItems": {
            "title": "🔢 Max Creator Rows",
            "minimum": 1,
            "maximum": 252,
            "type": "integer",
            "description": "Hard cap on charged creator rows. Realistic ceiling is 9 × (number of markets), because TikTok returns 3 hashtags × 3 creators per market slice and offers no page 2. The maximum here (252) is 9 × the 28 selectable markets — it is a real ceiling, not a placeholder.",
            "default": 10
          },
          "videosPerCreator": {
            "title": "🎥 Videos To Measure Per Creator",
            "minimum": 1,
            "maximum": 12,
            "type": "integer",
            "description": "How many of the creator's most recent videos get measured. TikTok's profile embed lists at most 12 recent videos (10–12 observed), so higher values simply measure everything that is listed.",
            "default": 3
          },
          "minVideoPlays": {
            "title": "▶️ Minimum Plays Per Video",
            "minimum": 0,
            "type": "integer",
            "description": "Drop measured videos below this play count from the output arrays and from the averages. Leave empty to keep every measured video."
          },
          "includeVideoHashtags": {
            "title": "#️⃣ Hashtag & Mention Attribution",
            "type": "boolean",
            "description": "Extract each video's hashtags and @mentions from TikTok's own caption entity list (not a caption regex).",
            "default": true
          },
          "includeSoundDetails": {
            "title": "🎵 Sound Attribution",
            "type": "boolean",
            "description": "Add the sound id, title, author and original-vs-borrowed flag per video, so you can tell whether the creator trended or the sound did.",
            "default": true
          },
          "includeSaveCounts": {
            "title": "💾 Save / Bookmark Count (extra request per video)",
            "type": "boolean",
            "description": "Saves are not published on the fast embed surface. Turn this on to read each measured video's watch page as well, which adds collect_count and save_rate_pct per video plus an average per creator. Costs one extra request per measured video.",
            "default": false
          },
          "includeCreatorRollups": {
            "title": "📈 Per-Creator Rollups",
            "type": "boolean",
            "description": "Add derived averages per creator: plays, likes, comments, shares, engagement rate, video duration, original-sound share and the top video.",
            "default": true
          },
          "videoChildDataset": {
            "title": "🎞️ Also Write A Flat Video Table",
            "type": "boolean",
            "description": "Mirror every measured video as its own row into a named dataset (TIKTOK-CREATOR-VIDEOS). Never charged.",
            "default": false
          },
          "failOnEmptyResults": {
            "title": "🚨 Fail Loudly On Zero Creators",
            "type": "boolean",
            "description": "Abort the run with an error instead of finishing green with an empty dataset when TikTok returns no creators at all.",
            "default": true
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy Configuration",
            "type": "object",
            "description": "Optional. Used only for tiktok.com profile and video fetches; the trending board is fetched directly. Your exact group / country / session choice is respected — nothing is silently escalated."
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}