**TikTok**, whose [mainland Chinese](https://en.wikipedia.org/wiki/Mainland_China "Mainland China") counterpart is **Douyin**,[[a]](https://en.wikipedia.org/wiki/TikTok#cite_note-3)[[3]](https://en.wikipedia.org/wiki/TikTok#cite_note-citizenlab/tiktok-douyin-4) is a short-form [video hosting service](https://en.wikipedia.org/wiki/Online_video_platform "Online video platform") owned by Chinese internet company [ByteDance](https://en.wikipedia.org/wiki/ByteDance "ByteDance"). It hosts user-submitted videos, which can range in duration from three seconds to 10 minutes.[[4]](https://en.wikipedia.org/wiki/TikTok#cite_note-3_Minutes-5) It can be accessed with a [smart phone](https://en.wikipedia.org/wiki/Smart_phone "Smart phone") [app](https://en.wikipedia.org/wiki/Software_application "Software application").
Since its launch, TikTok has become one of the world's most popular [social media](https://en.wikipedia.org/wiki/Social_media "Social media") platforms, using recommendation algorithms that were better than alternative apps at connecting content creators with new audiences.[[5]](https://en.wikipedia.org/wiki/TikTok#cite_note-CNNFung2024-6) Many of its users are young, of [Generation Z](https://en.wikipedia.org/wiki/Generation_Z "Generation Z"). In April 2020, TikTok surpassed two billion mobile downloads worldwide.[[6]](https://en.wikipedia.org/wiki/TikTok#cite_note-7) [Cloudflare](https://en.wikipedia.org/wiki/Cloudflare "Cloudflare") ranked TikTok the [most popular website](https://en.wikipedia.org/wiki/List_of_most-visited_websites) of 2021, surpassing [Google](https://en.wikipedia.org/wiki/Google_Search "Google Search").[[7]](https://en.wikipedia.org/wiki/TikTok#cite_note-8) The popularity of TikTok has allowed viral trends in [food](https://en.wikipedia.org/wiki/TikTok_food_trends "TikTok food trends") and [music](https://en.wikipedia.org/wiki/TikTok_Billboard_Top_50 "TikTok Billboard Top 50") to take off and increase the platform's [cultural impact](https://en.wikipedia.org/wiki/Cultural_impact_of_TikTok "Cultural impact of TikTok") worldwide.[[8]](https://en.wikipedia.org/wiki/TikTok#cite_note-9)
### 🎵 About This Actor
All-in-One general purpose TikTok Scraper
**Features :**
- ⭐search videos, users, live.
- ⭐search by hashtag.
- ⭐search by place.
- ⭐search music.
- ⭐access user specific data: info, followers, following, videos, playlist (mix)
- ⭐autodetect tiktok.com URL (aka. Starting URL) input.
- ⭐minimal inputs.
- ⭐directly open media/video/music URLs (via browser/cookie synchronize) or download individual video (watermarked or unwatermarked) to key-value storage.
- ⭐directly access tiktok.com web internal API, no browser emulation, fast and small memory usage.
- ⭐multiple queries in single request.
- ⭐small docker file size (only 100 mb), fast loading.
### 🎵 IMPORTANT NOTES
To be able to view media file URLs (covers, videos, etc.), you need to synchronize your browser's **Internal Values** *(cookies)* with this Actor, Otherwise, you won’t be able to open the media URLs provided by the Actor results. There are 3 cookies needed from **tiktok.com** domain :
- 🆔`ttwid`
- 🆔`tt_chain_token`
- 🆔`tt_csrf_token`
> This process doesn't requires your login info. You can first **Log Out** from **TikTok** if you want or use new fresh ***Chrome Incognito*** window.
Please visit https://www.tiktok.com and find these 3 cookie values from your browser *(device)* and copy paste here:
**Advanced Options**
### 🎵 Video Download
To open video URLs directly from your browser, you can ***synchronize*** your browser with the Actor (recommended, see above), or download individual video to default Key-Value storage.
***example:***
```yaml
{ "query": ["7112413115530104090/download"] }
````
The resulting data will same as normal, except link to video URL will be replaced with link to Key-Value storage URLs.
***example:***
```yaml
{
"id": "7112413115530104090",
...
"video": {
# watermarked
"downloadAddr": "https://api.apify.com/v2/key-value-stores/...",
...
# no-watermarked
"playAddr": "https://api.apify.com/v2/key-value-stores/...",
}
...
}
```
### 🎵 Quick Guide
#### TikTok Query Language
```html
[ [ 
### 🎵 ToolTips
#### ❓QUERY :
|Format|Section / Commands |Example|
|-|-|-|
|**KEYWORDS**|`top:` `users:` `videos:` `music:` `live:`|`videos:square pants`
|**explore:**|`home` `CATEGORY_ID` `CATEGORY_NAME`|`explore:comedy`
|**#HASHTAG**|`/info` `/videos` | `#music/videos`
|**@USER**|`/info` `/videos` `/playlist` `/following` `/followers`|`@elonmusk/videos`
|**VIDEO\_ID**|`/info` `/comments` `/related` `/download`|`7112413115530104090/comments`
|**playlist:PLAYLIST\_ID**||`playlist:XXXXXXXXXXXXXX`
|**channel:CHANNEL\_ID**||`channel:dance`
|**music:MUSIC\_ID**|`/info` `/videos`|`music:7112413142386297627/videos`
|**place:PLACE\_ID**|`/info` `/videos`|`place:22535865204947327/videos`
|**URL**||`https://www.tiktok.com/search?q=square pants`
# Actor input Schema
## `query` (type: `array`):
💡 Search Terms or QUERY
## `limit` (type: `integer`):
💡 Minimum number of results (per query)
## `dev_proxy_config` (type: `object`):
💡 Supported protocol:HTTP(S), SOCKS5
{http|socks5}://{user:pass}@{hostname|ip-address}:portExample:
socks5://example.com:9000
## `dev_custom_headers` (type: `array`):
💡 Additional HTTP Headers
## `dev_custom_cookies` (type: `array`):
💡 Additional HTTP Cookies
## `dev_transform_fields` (type: `array`):
💡 Transform the resulting output. Select only needed fields.For nested object use DOT. For example:
address.streetAddress
For nested array use NUMBER (index of array element starting from index=0). For example:
images.0.url## `dev_dataset_name` (type: `string`): 💡 Save results into custom named Dataset, use mask to customize dataset name
{ACTOR} = actor name
{DATE} = date (YYYYMMDD)
{TIME} = time (HHMMSS)This masks can be used to autogenerate Dataset Name.
example:
data-{DATE}Depending on today date the dataset name will be:
data-20230603default:
data-{ACTOR}-{DATE}-{TIME}
## `dev_dataset_clear` (type: `boolean`):
Clear Dataset before insert/update.
## `dev_no_strip` (type: `boolean`):
💡 Keep/Save empty values (NULL, FALSE, empty ARRAY, empty OBJECT, empty STRING)
## Actor input object example
```json
{
"query": [
"square pants",
"music:iwan fals"
],
"limit": 5
}
```
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the 'HTTP(S), SOCKS5
{http|socks5}://{user:pass}@{hostname|ip-address}:portExample:
socks5://example.com:9000"
},
"dev_custom_headers": {
"title": "📜 HTTP HEADERS",
"type": "array",
"description": "💡 Additional HTTP Headers",
"items": {
"type": "object",
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"title": "Key"
},
"value": {
"type": "string",
"title": "Value"
}
}
}
},
"dev_custom_cookies": {
"title": "🍰 HTTP COOKIES",
"type": "array",
"description": "💡 Additional HTTP Cookies",
"items": {
"type": "object",
"required": [
"key",
"value"
],
"properties": {
"key": {
"type": "string",
"title": "Key"
},
"value": {
"type": "string",
"title": "Value"
}
}
}
},
"dev_transform_fields": {
"title": "♻️ CUSTOM FIELD",
"type": "array",
"description": "💡 Transform the resulting output. Select only needed fields.For nested object use DOT. For example:
address.streetAddress
For nested array use NUMBER (index of array element starting from index=0). For example:
images.0.url", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "title": "Key" }, "value": { "type": "string", "title": "Value" } } } }, "dev_dataset_name": { "title": "📁 CUSTOM STORAGE", "type": "string", "description": "💡 Save results into custom named Dataset, use mask to customize dataset name
{ACTOR} = actor name
{DATE} = date (YYYYMMDD)
{TIME} = time (HHMMSS)This masks can be used to autogenerate Dataset Name.
example:
data-{DATE}Depending on today date the dataset name will be:
data-20230603default:
data-{ACTOR}-{DATE}-{TIME}"
},
"dev_dataset_clear": {
"title": "Clear Storage",
"type": "boolean",
"description": "Clear Dataset before insert/update."
},
"dev_no_strip": {
"title": "Disable data cleansing",
"type": "boolean",
"description": "💡 Keep/Save empty values (NULL, FALSE, empty ARRAY, empty OBJECT, empty STRING)"
}
}
},
"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
}
}
}
}
}
}
}
}
}
}
```