{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Data Scraper: Creator & Audience Leads",
    "description": "TikTok Data Scraper: Extract creator profiles, videos, followers, likes, comments, views, bios, and available public contact details. Build enriched creator and audience lead lists for influencer research, prospecting, competitor analysis, and social media intelligence.",
    "version": "0.1",
    "x-build-id": "WiD9bb2Cq5SpaBpSf"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/api-empire~tiktok-data-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-api-empire-tiktok-data-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/api-empire~tiktok-data-scraper/runs": {
      "post": {
        "operationId": "runs-sync-api-empire-tiktok-data-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/api-empire~tiktok-data-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-api-empire-tiktok-data-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": {
          "userUrls": {
            "title": "🔗 User URLs, Usernames or IDs",
            "type": "array",
            "description": "One or more profiles. Examples: https://www.tiktok.com/@taylorswift · taylorswift · @taylorswift · 107955",
            "items": {
              "type": "string"
            }
          },
          "categories": {
            "title": "🗂️ Categories to scrape",
            "type": "array",
            "description": "Pick which kinds of content to collect for each profile above. Multiple selections are supported. Note: 'Followers' is not exposed by the underlying data source for any profile — enable it to see an explicit log notice rather than a silent empty result.",
            "items": {
              "type": "string",
              "enum": [
                "videos",
                "favourite_videos",
                "followers",
                "following",
                "search",
                "user_info"
              ],
              "enumTitles": [
                "📹 User Videos",
                "❤️ User Favourite Videos",
                "👥 Followers (currently unavailable — logs a clear notice)",
                "🫂 Following",
                "🔍 User Search",
                "👤 User Info"
              ]
            },
            "default": [
              "videos"
            ]
          },
          "maxUserResults": {
            "title": "🔢 Max results per category",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum items to fetch per profile / section. Ignored when '🌊 Scrape all results' is enabled. Minimum 40.",
            "default": 10
          },
          "scrapeAllUserResults": {
            "title": "🌊 Scrape all available results",
            "type": "boolean",
            "description": "Ignore the limit above and collect everything available for each profile.",
            "default": false
          },
          "videoUrlsComments": {
            "title": "🔗 Video URLs or IDs",
            "type": "array",
            "description": "TikTok video URLs or IDs to scrape comments from.",
            "items": {
              "type": "string"
            }
          },
          "commentsPerUrl": {
            "title": "🔢 Max comments per video",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum comments per video. Ignored when '🌊 Scrape all comments' is on. Minimum 40.",
            "default": 10
          },
          "scrapeAllComments": {
            "title": "🌊 Scrape all comments",
            "type": "boolean",
            "description": "Collect every available comment per video (slower, more usage).",
            "default": false
          },
          "repliesPerComment": {
            "title": "↳ Max replies per comment",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum replies per comment. Set to 0 to skip replies entirely. Ignored when '🌊 Scrape all replies' is on.",
            "default": 0
          },
          "scrapeAllReplies": {
            "title": "🌊 Scrape all replies",
            "type": "boolean",
            "description": "Collect every available reply for each comment (slower, more usage).",
            "default": false
          },
          "hashtags": {
            "title": "#️⃣ Hashtag names or URLs",
            "type": "array",
            "description": "TikTok hashtag names or URLs to scrape videos from.",
            "items": {
              "type": "string"
            }
          },
          "videosPerHashtag": {
            "title": "🔢 Max videos per hashtag",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum videos per hashtag. Ignored when '🌊 Scrape all hashtag videos' is on. Minimum 40.",
            "default": 10
          },
          "scrapeAllHashtagVideos": {
            "title": "🌊 Scrape all hashtag videos",
            "type": "boolean",
            "description": "Collect every available video for each hashtag (slower, more usage).",
            "default": false
          },
          "hashtagRegion": {
            "title": "🌍 Region",
            "pattern": "^[A-Za-z]{2}$",
            "type": "string",
            "description": "Two-letter country code used for localization (e.g. US, GB, IN).",
            "default": "US"
          },
          "musicUrls": {
            "title": "🔗 Music URLs or IDs",
            "type": "array",
            "description": "TikTok music URLs or IDs to scrape videos from.",
            "items": {
              "type": "string"
            }
          },
          "videosPerMusic": {
            "title": "🔢 Max videos per music",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum videos per music track. Ignored when '🌊 Scrape all music videos' is on. Minimum 40.",
            "default": 10
          },
          "scrapeAllMusicVideos": {
            "title": "🌊 Scrape all music videos",
            "type": "boolean",
            "description": "Collect every available video for each music track (slower, more usage).",
            "default": false
          },
          "playlistIDs": {
            "title": "🆔 Playlist IDs",
            "type": "array",
            "description": "TikTok playlist IDs to scrape videos from.",
            "items": {
              "type": "string"
            }
          },
          "videosPerPlaylist": {
            "title": "🔢 Max videos per playlist",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum videos per playlist. Ignored when '🌊 Scrape all playlist videos' is on. Minimum 40.",
            "default": 10
          },
          "scrapeAllPlaylistVideos": {
            "title": "🌊 Scrape all playlist videos",
            "type": "boolean",
            "description": "Collect every available video for each playlist (slower, more usage).",
            "default": false
          },
          "videoDetailsList": {
            "title": "🔗 Video IDs or URLs",
            "type": "array",
            "description": "TikTok video IDs or URLs to retrieve full details for.",
            "items": {
              "type": "string"
            }
          },
          "discoverCreatorLeads": {
            "title": "🕵️ Auto-discover creator leads",
            "type": "boolean",
            "description": "When ON, every unique creator whose videos appear in your Hashtag, Search, Music, Playlist, User-videos or User-favourites results is fetched once (profile lookup) and promoted to a creator-lead row with bio, bioLink, verified status, follower count and Instagram/Twitter/YouTube handles. Requires no manual handle list — creators are discovered from the results themselves.",
            "default": false
          },
          "discoverCommenterLeads": {
            "title": "💬 Auto-discover commenter leads",
            "type": "boolean",
            "description": "When ON, every unique commenter and replier found while collecting comments in the 💬 Comments & Replies section above is promoted to its own audience-lead row (bio, verified status, follower count, social handles). Uses data already present on the comment — no extra requests.",
            "default": false
          },
          "onlyVerifiedLeads": {
            "title": "✅ Only verified accounts",
            "type": "boolean",
            "description": "When ON, only creator/commenter leads carrying a verified TikTok badge are kept; unverified leads are dropped before saving.",
            "default": false
          },
          "minLeadFollowerCount": {
            "title": "🔢 Minimum follower count for leads",
            "minimum": 0,
            "type": "integer",
            "description": "Skip creator/commenter leads with fewer followers than this. Note: TikTok frequently reports 0 for a commenter's own follower count on the comment payload — set to 0 to keep everyone.",
            "default": 0
          },
          "maxDiscoveredLeads": {
            "title": "🛑 Max total leads (0 = unlimited)",
            "minimum": 0,
            "type": "integer",
            "description": "Stop discovering new creator/commenter leads once this many have been saved in this run. 0 = unlimited (bounded only by how many unique creators/commenters the run actually encounters).",
            "default": 0
          },
          "minRequestInterval": {
            "title": "⏱️ Minimum delay between requests (seconds)",
            "minimum": 0,
            "maximum": 10,
            "type": "number",
            "description": "Seconds to wait between consecutive requests. Lower is faster but more likely to be rate-limited.",
            "default": 1.2
          },
          "maxRetries": {
            "title": "🔁 Max retries per request",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "How many times to retry a failed/blocked request before giving up.",
            "default": 3
          },
          "apiKey": {
            "title": "🔑 Premium data key (optional)",
            "type": "string",
            "description": "Optional key that lifts the rate limit for faster collection. Leave empty for the free tier.",
            "default": ""
          },
          "proxyConfiguration": {
            "title": "🛡️ Proxy configuration",
            "type": "object",
            "description": "By default the scraper runs WITHOUT a proxy. If TikTok blocks the direct connection, it automatically escalates: 🛡️ datacenter → 🏠 residential, then sticks with residential. You can also force a proxy here.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}