Docs
Query Videos
There is a new version of this API available in TikTok API v2: Query Videos
Overview
The video/query/
endpoint, given a user and a list of video ids, can check if the videos belong to the requesting user and fetch the data of videos belonging to the user. It can be used to refresh the given videos' cover image url TTL. Number of video ids should not be larger than 20 at a time.
HTTP URL | https://open-api.tiktok.com/video/query/ |
HTTP Method | POST |
Scope | video.list |
Request
Headers
Key | Type | Description | Example | Required |
Content-Type | string | "application/json" | "application/json" | Yes |
Body
Key | Type | Description | Example | Required |
access_token | string | The token that bears the authorization of the TikTok user, which is obtained through /oauth/access_token/. | act.example12345Example12345Example | Yes |
filters | object | Fields:
| { "video_ids": ["1234565570247476230"] } | Yes |
fields | set<string> | The set of optional video fields Choose fields from: VideoObject's fields | ["embed_link"] | Yes |
Request Example
curl -L -X POST 'https://open-api.tiktok.com/video/query/' \
-H 'Content-Type: application/json' \
--data-raw '{
"access_token": "act.example12345Example12345Example",
"filters": {
"video_ids": ["1234568030997662933", "1234580793298373833"]
},
"fields": ["id", "title"]
}'
Response
Key | Type | Description | Required |
data | map<string, list<VideoObject>> | videos: list<video object> | Yes |
error | Object | Error object | Yes |
VideoObject
Field | Type | Description | Scope |
id | string | Unique identifier for the TikTok video. Also called "item_id" | video.list |
create_time | int64 | UTC Unix epoch (in seconds) of when the TikTok video was posted. | video.list |
cover_image_url | string | A CDN link for the video's cover image. The image is static. Due to our trust and safety policies, the link has a TTL of 6 hours. | video.list |
share_url | string | A shareable link for this TikTok video. Note that the website behaves differently on Mobile and Desktop devices. | video.list |
video_description | string | The description that the creator has set for the TikTok video. Max length: 150 | video.list |
duration | int32 | The duration of the TikTok video in seconds. | video.list |
height | int32 | The height of the TikTok video. | video.list |
width | int32 | The width of the TikTok video. | video.list |
title | string | The video title. Max length: 150 | video.list |
embed_html | string | HTML code for embedded video | video.list |
embed_link | string | Video embed link of tiktok.com | video.list |
like_count | int32 | Number of likes of the video. Included when requested in the fields. | video.list |
comment_count | int32 | Number of comments of the video. Included when requested in the fields. | video.list |
share_count | int32 | Number of shares of the video. Included when requested in the fields. | video.list |
view_count | int64 | Number of views of the video. Included when requested in the fields. | video.list |
Example
{
"data":{
"videos":[
{
"id":"1234568030997662933",
"title":"Test Video 32"
},
{
"id":"1234580793298373833",
"title":"Test Video 22"
}
]
},
"error":{
"code":0,
"message":""
}
}