{
"openapi": "3.0.1",
"info": {
"title": "Tiktok Live Scraper",
"description": "Extract active and trending TikTok live rooms, creator info, and public audience signals for creator monitoring, event tracking, and live trend analysis.",
"version": "1.0",
"x-build-id": "In7n5odD05WEaApHh"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/coregent~tiktok-live-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-coregent-tiktok-live-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/coregent~tiktok-live-scraper/runs": {
"post": {
"operationId": "runs-sync-coregent-tiktok-live-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/coregent~tiktok-live-scraper/run-sync": {
"post": {
"operationId": "run-sync-coregent-tiktok-live-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": {
"creatorProfiles": {
"title": "Creators to check",
"type": "array",
"description": "TikTok creators to check for an active LIVE session. Accepts @username, username, or a full profile URL. Filling this runs creator discovery — there is no separate mode to select. Charged per creator checked, whether or not they are live; offline creators still return a NOT_LIVE row so you can see the result.",
"items": {
"type": "string"
},
"default": []
},
"keywords": {
"title": "Keywords to search (one search per keyword)",
"type": "array",
"description": "Terms to search for live rooms. Filling this runs keyword discovery — there is no separate mode to select. Each keyword runs as its own search and is capped separately by \"Max live rooms per keyword\", so five keywords means five searches.",
"items": {
"type": "string"
},
"default": []
},
"includeTrending": {
"title": "Also discover trending rooms",
"type": "boolean",
"description": "Adds a trending sweep alongside your creators and keywords. You do not need this for a trending-only run — if you leave creators and keywords empty, trending runs automatically. Turn it on only when you want trending in addition to creators or keywords, and remember it adds up to \"Max live rooms per source\" more results.",
"default": false
},
"trendingTerms": {
"title": "Trending seed terms (advanced — replaces the built-in list)",
"type": "array",
"description": "Advanced override for the trending sweep. Trending normally uses a built-in list of broad terms (live, gaming, music, chat, dance, cooking, sports, beauty, comedy, talk); supply your own here to point it at a vertical instead. This is not the same as \"Keywords to search\" — these terms seed one trending sweep sharing a single budget, whereas each keyword is a separate, separately-capped search. Leave empty to use the defaults.",
"items": {
"type": "string"
},
"default": []
},
"minViewerCount": {
"title": "Minimum viewer count",
"minimum": 0,
"type": "integer",
"description": "Only return rooms with at least this many current viewers. Rooms below the threshold are discarded before billing, so you are not charged for them. Rooms whose viewer count TikTok does not expose are also excluded when this is above 0. Set to 0 to include every room.",
"default": 0
},
"sortBy": {
"title": "Sort by",
"enum": [
"priorityScore",
"viewerCount",
"default"
],
"type": "string",
"description": "How to order results. priorityScore — the built-in 0-100 scoring heuristic (recommended). viewerCount — largest audience first. default — keep TikTok's own discovery order. Sorting is applied per discovery source before results are saved.",
"default": "priorityScore"
},
"maxRooms": {
"title": "Max live rooms per source",
"minimum": 0,
"maximum": 10000,
"type": "integer",
"description": "Cap per discovery source, not per run. Trending counts as one source. Use 'Max live rooms in total' below for an absolute ceiling on what a run can cost. Setting this to 0 removes the per-source cap and can significantly increase runtime and cost — prefer a finite value in production.",
"default": 300
},
"maxRoomsPerKeyword": {
"title": "Max live rooms per keyword",
"minimum": 1,
"maximum": 1000,
"type": "integer",
"description": "Cap applied to each keyword separately. With 5 keywords at 50, a run can save up to 250 rooms. Start small on a first run to see what a keyword returns before raising it.",
"default": 50
},
"maxTotalRooms": {
"title": "Max live rooms in total",
"minimum": 0,
"maximum": 50000,
"type": "integer",
"description": "Absolute ceiling for the whole run across every mode, source, and keyword. This is the hard cost cap — the run stops collecting once it is reached. Set to 0 to remove it (not recommended: a multi-mode run with many keywords can then save far more rooms than expected).",
"default": 1000
},
"includeCreatorFields": {
"title": "Include creator fields",
"type": "boolean",
"description": "Include creator-level fields (username, display name, followers, bio, verified status) on each row.",
"default": true
},
"includeActivitySignals": {
"title": "Include activity signals",
"type": "boolean",
"description": "Include audience and engagement fields (viewer count, likes, comments, shares) on each row.",
"default": true
},
"includeStreamUrls": {
"title": "Include playback stream URLs",
"type": "boolean",
"description": "Include the live stream playback URLs (HLS, FLV, RTMP) plus quality, resolution, and expiry on each row. These URLs are signed and short-lived — check streamUrlExpiresAt before using them.",
"default": true
},
"includeSummary": {
"title": "Append run summary",
"type": "boolean",
"description": "Append one aggregated summary record at the end of the dataset with run statistics, top creators, and audience distribution. The summary is not charged. Note that it has a different shape from a live-room row, which matters if you export straight to CSV.",
"default": true
},
"deduplicateRooms": {
"title": "Deduplicate rooms",
"type": "boolean",
"description": "Remove duplicate rooms when the same live room is found by more than one discovery route — for example by both trending and a keyword. Duplicates are dropped before billing, so a room is never charged twice. Turn off only if you want one row per discovery route.",
"default": true
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Proxy used for TikTok requests. Apify Datacenter or no proxy are the supported options — both work reliably for TikTok LIVE discovery at this actor’s concurrency. Apify Residential is not supported and the run will stop immediately if it is selected. If you need residential routing, add your own provider under Custom proxy URLs (for example http://user:pass@proxy.iproyal.com:12321) — that traffic goes through your provider, not Apify.",
"default": {
"useApifyProxy": true
}
}
}
},
"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
}
}
}
}
}
}
}
}
}
}