Video List

Overview

The video/list/ endpoint can return a paginated list of given user's public TikTok video posts, sorted by create_time in descending order. There is a POST method and a GET method, with the POST method providing optional additional video metadata.

Authorization Scopes

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

Documentation

Endpoint

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

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/`.
cursor	int64	Cursor for pagination. If `response.data.has_more` is true, pass in the `response.data.cursor` to the next request will yield the results for the next page. Note: the cursor value is a UTC Unix timestamp in milli-seconds. You can pass in a customized timestamp to fetch the user's videos posted after the provided timestamp.
max_count	int32	The maximum number of videos that will be returned from each page. Default is 10. Maximum is 20. Note: due our trust and safety policies, it is possible that the endpoint returns less than max_count number of videos even if `response.data.has_more` is `true`.
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
cursor	int64	Cursor for pagination.
has_more	bool	Whether there are more videos that can be fetched.
videos	VideoListVideoInfo Struct	A list of video structs.

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/list/' \
-H 'Content-Type: application/json' \
--data-raw '{
    "access_token": "act.1a4b9d05d9ad1a56294b93b5609cdfbdNzQgbpbUWyFNvhC9QqIvKEjuuPHn",
    "open_id": "723f24d7-e717-40f8-a2b6-cb8464cd23b4",
    "cursor": 0,
    "max_count": 10,
    "fields": ["embed_html", "embed_link", "share_count"]
}'