TikTok for Developers

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: set<string>

{

"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":""
    }
}