Skip to main content
TikTok for DevelopersTikTok for Developers

Docs

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