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"]
}'