Skip to main content
TikTok for DevelopersTikTok for Developers

Docs

Query Videos

Overview

Given an authorized user and a list of video IDs, the /v2/video/query/ endpoint verifies that the videos belong to the user and returns video details. It can be used to refresh the given videos' cover image URL TTL. Up to 20 video IDs can be included per request.

HTTP URL

https://open.tiktokapis.com/v2/video/query/

HTTP Method

POST

Scope

video.list

Request

Headers

Key

Type

Description

Example

Required

Authorization

string

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

Bearer act.1d1021d2aee3d41fee2d2add43456badMFZnrhFhfWotu3Ecuiuka27L56lr!2323

true

Content-Type

string

indicate the original media type of the resource

application/json

true

Query Parameters

Key

Type

Description

Example

Required

fields

string

The requested fields, choose from Video Object's fields:

[id, create_time, cover_image_url, share_url, video_description, duration, height, width, title, embed_html, embed_link, like_count, comment_count, share_count, view_count]

id,title,fps


true

Body

Key

Type

Description

Example

Required

filters

VideoFilters

Filter videos by video_ids


{

"video_ids":[

"7077642457847991554",

"7080217258529737986"

]

}

true

Request Example

curl -L -X POST 'https://open.tiktokapis.com/v2/video/query/?fields=id,title' \
-H 'Authorization: Bearer act.1d1021d2aee3d41fee2d2add43456badMFZnrhFhfWotu3Ecuiuka27L56lr!2323' \
-H 'Content-Type: application/json' \
--data-raw '{
    "filters": {
        "video_ids": [
            "7077642457847991554",
            "7080217258529737986"
        ]
    }
}'

Response

Key

Type

data

map<string, QueryUserVideoResponseData>

error

Error object

QueryUserVideoResponseData

Key

Type

Description

videos

list<video object>

A list of video objects

cursor

i64

Cursor for pagination. If response.has_more is true, pass in the response.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 before the provided timestamp.

has_more

bool

Whether there are more videos

Example

{
   "data":{
      "videos":[
         {
            "title":"Video 1",
            "id":"7077642457847991554"
         },
         {
            "title":"Video 2",
            "id":"7080217258529737986"
         }
      ],
      "cursor":1643332803000,
      "has_more":true
   },
   "error": {
      "code":"ok",
      "message":"",
      "log_id":"20220829194722CBE87ED59D524E727021"
   }
}