Docs
Query Videos
Request
HTTP URL | https://open.tiktokapis.com/v2/research/video/query/ |
HTTP Method | POST |
Scopes | research.data.basic (required) |
Headers
Key | Type | Description | Example | Required |
Content-Type | string | Indicate the original media type of the resource. | "application/json" | Yes |
Authorization | string | The client access token which is obtained through /v2/oauth/token/. | Bearer clt.1234asd2387jedyghgs4easd1234asdf84jenryhdlasuie4jh | Yes |
Query Parameters
Key | Type | Description | Example | Required |
fields | string | The requested fields. Choose from the Video Object's fields. | Complete list: id,video_description,create_time, region_code,share_count,view_count,like_count,comment_count, music_id,hashtag_names, username,effect_ids,playlist_id,voice_to_text | Yes |
Body
Key | Type | Description | Example | Required |
query | Query object (See the definition below) | A JSON object that contains three types of children: |
| Yes |
start_date | string | The lower bound of the video creation time | "20210102" | Yes |
end_date | string | The upper bound of video creation time The end_date must be no more than 30 days after the start_date | "20210123" | Yes |
max_count | int64 | The number of videos in response. Default is 20, max is 100. | 20 | No |
cursor | int64 | Retrieve video results starting from the specified index | 100 | No |
search_id | string | A search_id is a unique identifier assigned to a cached search result. This identifier enables the resumption of a prior search and retrieval of additional results based on the same search criteria. | "7201388525814961198" | No |
is_random | bool | Whether return results in random order | true | No |
Query
Key | Type | Description | Required |
and | list<Condition> | The | No |
or | list<Condition> | The | No |
not | list<Condition> | The | No |
Condition
Name | Type | Description |
field_name | string | The name of the field this condition is restricting One of: ["create_date", "username", "region_code", "video_id", "hashtag_name", "music_id", "effect_id", "video_length"] |
operation | string | One of: "EQ", "IN", "GT", "GTE", "LT", "LTE" |
field_values | list<string> | A list of restriction values |
Condition fields
Field Name | Description | Example |
create_date | The date the video was created, presented in the format YYYYMMDD | 20220910 |
username | The username of the video creator | "cookie_love_122" |
region_code | The abbreviated name of the country where the video was created | 'FR', 'TH', 'MM', 'BD', 'IT', 'NP', 'IQ', 'BR', 'US', 'KW', 'VN', 'AR', 'KZ', 'GB', 'UA', 'TR', 'ID', 'PK', 'NG', 'KH', 'PH', 'EG', 'QA', 'MY', 'ES', 'JO', 'MA', 'SA', 'TW', 'AF', 'EC', 'MX', 'BW', 'JP', 'LT', 'TN', 'RO', 'LY', 'IL', 'DZ', 'CG', 'GH', 'DE', 'BJ', 'SN', 'SK', 'BY', 'NL', 'LA', 'BE', 'DO', 'TZ', 'LK', 'NI', 'LB', 'IE', 'RS', 'HU', 'PT', 'GP', 'CM', 'HN', 'FI', 'GA', 'BN', 'SG', 'BO', 'GM', 'BG', 'SD', 'TT', 'OM', 'FO', 'MZ', 'ML', 'UG', 'RE', 'PY', 'GT', 'CI', 'SR', 'AO', 'AZ', 'LR', 'CD', 'HR', 'SV', 'MV', 'GY', 'BH', 'TG', 'SL', 'MK', 'KE', 'MT', 'MG', 'MR', 'PA', 'IS', 'LU', 'HT', 'TM', 'ZM', 'CR', 'NO', 'AL', 'ET', 'GW', 'AU', 'KR', 'UY', 'JM', 'DK', 'AE', 'MD', 'SE', 'MU', 'SO', 'CO', 'AT', 'GR', 'UZ', 'CL', 'GE', 'PL', 'CA', 'CZ', 'ZA', 'AI', 'VE', 'KG', 'PE', 'CH', 'LV', 'PR', 'NZ', 'TL', 'BT', 'MN', 'FJ', 'SZ', 'VU', 'BF', 'TJ', 'BA', 'AM', 'TD', 'SI', 'CY', 'MW', 'EE', 'XK', 'ME', 'KY', 'YE', 'LS', 'ZW', 'MC', 'GN', 'BS', 'PF', 'NA', 'VI', 'BB', 'BZ', 'CW', 'PS', 'FM', 'PG', 'BI', 'AD', 'TV', 'GL', 'KM', 'AW', 'TC', 'CV', 'MO', 'VC', 'NE', 'WS', 'MP', 'DJ', 'RW', 'AG', 'GI', 'GQ', 'AS', 'AX', 'TO', 'KN', 'LC', 'NC', 'LI', 'SS', 'IR', 'SY', 'IM', 'SC', 'VG', 'SB', 'DM', 'KI', 'UM', 'SX', 'GD', 'MH', 'BQ', 'YT', 'ST', 'CF', 'BM', 'SM', 'PW', 'GU', 'HK', 'IN', 'CK', 'AQ', 'WF', 'JE', 'MQ', 'CN', 'GF', 'MS', 'GG', 'TK', 'FK', 'PM', 'NU', 'MF', 'ER', 'NF', 'VA', 'IO', 'SH', 'BL', 'CU', 'NR', 'TP', 'BV', 'EH', 'PN', 'TF', 'RU' |
video_id | The unique identifier of the video | 6978662169214864645 |
hashtag_name | The hashtag associated with the video | "arianagrande", "celebrity" |
music_id | The music ID of the video. | 8978345345214861235 |
effect_id | The effect ID of the video. | 3957392342148643476 |
video_length | The duration of the video SHORT: <15s MID: 15 ~60s LONG: 1~5min EXTRA_LONG: >5min | "SHORT", "MID", "LONG", "EXTRA_LONG" |
Example
curl -L -X POST 'https://open.tiktokapis.com/v2/research/video/query/?fields=video_id,video_description,create_time' \
-H 'Authorization: Bearer clt.1234asd2387jedyghgs4easd1234asdf84jenryhdlasuie4jh' \
-H 'Content-Type: application/json' \
--data-raw '{
"query": {
"and": [
{
"operation": "IN",
"field_name": "region_code",
"field_values": ["JP", "US"]
},
{
"operation":"EQ",
"field_name":"hashtag_name",
"field_values":["animal"]
}
],
"not": [
{
"operation": "EQ",
"field_name": "video_length",
"field_values": ["SHORT"]
}
]
},
"max_count": 100,
"cursor": 0,
"start_date": "20230101",
"end_date": "20230115"
}'
Response
Key | Type | Example |
data | QueryVideoResponseData | { "videos": [...], "cursor": 100, "has_more": true, "search_id": "" } |
error | ErrorStruct | Error object |
Data Structures
QueryVideoResponseData
Field | Type | Description |
videos | list<Video Object> | A list of video objects that match the query |
cursor | int64 | Returns video results from the given index. |
has_more | bool | Whether there are more videos or not. |
search_id | string | A search_id is a unique identifier assigned to a cached search result. This identifier enables the resumption of a prior search and retrieval of additional results based on the same search criteria. |
Video Object
Field | Type | Description |
"id" | int64 | Unique identifier for the TikTok video. Also called "item_id" or "video_id" |
"create_time" | int64 | UTC Unix epoch (in seconds) of when the TikTok video was posted. (Inherited field from TNS research API) |
"username" | string | The video's author's username |
"region_code" | string | A two digit code for the country the video was posted in |
"video_description" | string | The description of the video, also known as the title |
"music_id" | int64 | The music_id used in the video |
"like_count" | int64 | The number of likes the video has received. |
"comment_count" | int64 | The number of comments the video has received. |
"share_count" | int64 | The number of shares the video has received. |
"view_count" | int64 | The number of video views the video has received. |
"effect_ids" | list<string> | The list of effect ids applied on the video |
"hashtag_names" | list<string> | The list of hashtag names that the video participates in |
"playlist_id" | int64 | The ID of playlist that the video belongs to |
"voice_to_text" | string | Voice to text and subtitles (for videos that have voice to text features on, show the texts already generated) |
Example
{
"data": {
"videos": [
{
"hashtag_names": [
"avengers",
"pov"
],
"region_code": "CA",
"create_time": 1633823999,
"effect_ids": [
"0"
],
"video_id": 702874395068494965,
"music_id": 703847506349838790,
"video_description": "lol #pov #avengers",
"view_count": 1050,
"comment_count": 2
},
...
],
"cursor": 100,
"search_id": "7201388525814961198",
"has_more": true
},
"error": {
"code": "ok",
"message": "",
"log_id": "20230113024658F0D7C5D6CA3A9B79C5B9"
}
}