Skip to main content
TikTok for DevelopersTikTok for Developers

Docs

Video Query

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.

Authorization Scopes

  • video.list gives read-only access to a user's public TikTok videos.

Documentation

Endpoint

POSThttps://open-api.tiktok.com/video/query/

Request

Request Body

Key

Type

Description

open_id

string

The TikTok user's unique identifier, which is obtained through /oauth/access_token/.

access_token

string

The token that bears the authorization of the TikTok user, which is obtained through /oauth/access_token/.

filter

object

Fields: 

video_ids: set<string>, max 20 video ids at a time. 


Example:

{"video_ids": ["6963640889373723909"] }

fields

set<string>

The set of optional video metadata.

Choose to include from: ["embed_html","embed_link","like_count","comment_count","share_count","view_count","title"].

Response

Response.data Struct

Key

Type

Description

videos

VideoListVideoInfo Struct

A list of requested video structs that belong to the user.

Response.error Struct

Key

Type

Description

code

int32

Error code.

message

string

Error message describing the reason.

log_id

string

Log id for tracing the log data.

VideoListVideoInfo Struct

Key

Type

Description

create_time

int64

UTC Unix epoch (in seconds) of when the TikTok video was posted.

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.

share_url

string

A sharable link for this TikTok video. Note that the website behaves differently on Mobile and Desktop devices.

video_description

string

The description that the creator has set for the TikTok video.

duration

int32

The duration of the TikTok video in seconds.

height

int32

The height of the TikTok video.

width

int32

The width of the TikTok video.

id

string

Unique identifier for the TikTok video.

title

string

Title of the video. Included when requested in the fields.

embed_html

string

An embed html of the video. Included when requested in the fields.

embed_link

string

An embed link of the video. Included when requested in the fields.

like_count

int32

Number of likes of the video. Included when requested in the fields.

comment_count

int32

Number of comments of the video. Included when requested in the fields.

share_count

int32

Number of shares of the video. Included when requested in the fields.

view_count

int64

Number of views of the video. Included when requested in the fields.

Code Example

Example using curl command:

curl -L -X POST 'https://open-api.tiktok.com/video/query/' \
-H 'Content-Type: application/json' \
--data-raw '{
    "access_token": "act.1a4b9d05d9ad1a56294b93b5609cdfbdNzQgbpbUWyFNvhC9QqIvKEjuuPHn",
    "open_id": "723f24d7-e717-40f8-a2b6-cb8464cd23b4",
    "filters": {
        "video_ids": ["6948568030997662982", "6935880793298373894"]
    },
    "fields": ["embed_html", "embed_link"]
}'