TikTok 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.example12345Example12345Example

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.example12345Example12345Example' \
-H 'Content-Type: application/json' \
--data-raw '{
    "filters": {
        "video_ids": [
            "1234123412345678567",
            "1010102020203030303"
        ]
    }
}'

Response

Key

Type

data

map<string, QueryUserVideoResponseData>

error

Error object

QueryUserVideoResponseData

Key

Type

Description

videos

list<video object>

A list of video objects

Example

{
   "data":{
      "videos":[
         {
            "title":"Video 1",
            "id":"1234123412345678567"
         },
         {
            "title":"Video 2",
            "id":"1010102020203030303"
         }
      ]
   },
   "error": {
      "code":"ok",
      "message":"",
      "log_id":"20220829194722CBE87ED59D524E727021"
   }
}