Skip to content
TikTok Shop Partner API

Get Shop Videos Performance Details

GET
/analytics/202609/shop_videos/batch_performance

Returns detailed performance metrics for the requested videos.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
shop_cipher
required
string

Identifies the shop. Obtain it from the Get Authorized Shops API.

video_ids
required
Array<integer>

The IDs of the shop videos whose performance details are requested.

start_date_ge
required
string format: date

Start date (ISO 8601 YYYY-MM-DD format) in shop registered timezone. In the parameter name, “ge” refers to “greater than or equal to” (inclusive)

The time range between start and end must not exceed 60 days.

end_date_lt
required
string format: date

End date (ISO 8601 YYYY-MM-DD format) in shop registered timezone. In the parameter name, “lt” refers to “less than” (exclusive)

The time range between start and end must not exceed 60 days.

granularity
string
Allowed values: ALL 1D

Granularity of the data. Available values: ALL, 1D Default value: ALL

  • ALL: aggregate
  • 1D: daily
currency
string
Allowed values: USD LOCAL

Currently, only local currency is supported in the response.

Available values: USD, LOCAL Default value: LOCAL

  • USD: US dollars
  • LOCAL: local currency where the shop is located

Responses

Section titled “Responses”

200

Section titled “200”

Success

Media typeapplication/json
object
code

Status code; 0 means success.

integer format: int64
message

Success or failure message.

string
request_id

Request log ID.

string
data
object
latest_available_date

Latest date in local timezone where data is ready (ISO 8601 format).

string format: date
videos

Performance details for the requested videos.

Array<object>
object
error

Error information when performance details for this video could not be returned.

object
code

Error Code

string
message

Error Description

string
performance

Performance details for this video. Returned when the video is processed successfully.

object
intervals

Interval data for the requested time range.

Array<object>
object
end_date

End date of the interval, exclusive.

string format: date
sales

Sales performance data.

object
overall

Overall sales performance data.

object
ctr

Product clicks from the video divided by impressions of all video products.

string
customers

The total number of customers who placed orders directly from the shoppable video.

integer format: int64
gmv

Gross merchandise value generated directly from the shoppable video.

object
amount

GMV amount in the corresponding currency.

string
currency

GMV currency code (ISO 4217 standard). If LOCAL currency is requested, the value will be the local currency code of where the shop is registered (e.g. GBP).

string
gpm

GMV generated per 1,000 video views.

object
amount

GPM amount in the corresponding currency.

string
currency

GPM currency code (ISO 4217 standard). If LOCAL currency is requested, the value will be the local currency code of where the shop is registered (e.g. GBP).

string
items_sold

The total number of items sold directly from the shoppable video.

integer format: int64
product_clicks

The number of product clicks from the video.

integer format: int64
product_impressions

The number of impressions of all video products.

integer format: int64
start_date

Start date of the interval, inclusive.

string format: date
traffic

Traffic performance of the video.

object
comments

The number of comments received by the video.

integer format: int64
likes

The number of likes received by the video.

integer format: int64
new_followers

The number of new followers attributed to the video.

integer format: int64
shares

The number of times the video was shared.

integer format: int64
views

The number of video views.

integer format: int64
viewer_profile

Viewer profile of the video.

Array<object>
object
age_distribution

Distribution of viewers by age range.

Array<object>
object
age

Possible values:

  • 18-24
  • 25-34
  • 35-44
  • 45-54
  • 55+
string
percentage

Proportion for the corresponding age group within this viewer profile, expressed as a decimal fraction.

string
country_distribution

Distribution of viewers by country or region.

Array<object>
object
country_code

The region of the viewer’s TikTok account.

string
percentage

Proportion for the corresponding country within this viewer profile, expressed as a decimal fraction.

string
gender_distribution

Distribution of viewers by gender.

Array<object>
object
gender

Viewer gender. Possible values:

  • MALE: male viewers

  • FEMALE: female viewers

string
Allowed values: MALE FEMALE
percentage

Proportion for the corresponding gender within this viewer profile, expressed as a decimal fraction.

string
type

Viewer profile type. Possible values: NEW_FOLLOWER, VIEWERS.

string
Allowed values: NEW_FOLLOWER VIEWERS
video

Basic information about the video.

object
duration

The video duration.

integer format: int64
id

The video ID.

string
play_url

The video playback URL.

string
thumbnail_url

The video thumbnail URL.

string
title

The video title.

string
username

The username of the video creator.

string
video_post_time

The time when the video was posted.

string
video_id

The requested video ID.

string
Example
{
  "code": 0,
  "data": {
    "latest_available_date": "2024-09-07",
    "videos": [
      {
        "error": {
          "code": "300001",
          "message": "Invalid video ID."
        },
        "performance": {
          "intervals": [
            {
              "end_date": "2024-09-08",
              "sales": {
                "overall": {
                  "ctr": "0.029",
                  "customers": 12,
                  "gmv": {
                    "amount": "230.02",
                    "currency": "USD"
                  },
                  "gpm": {
                    "amount": "230.02",
                    "currency": "USD"
                  },
                  "items_sold": 22,
                  "product_clicks": 21232,
                  "product_impressions": 32092
                }
              },
              "start_date": "2024-09-01",
              "traffic": {
                "comments": 8,
                "likes": 2,
                "new_followers": 11,
                "shares": 23,
                "views": 76649
              }
            }
          ],
          "viewer_profile": [
            {
              "age_distribution": [
                {
                  "age": "25-34",
                  "percentage": "0.293"
                }
              ],
              "country_distribution": [
                {
                  "country_code": "MY",
                  "percentage": "0.993"
                }
              ],
              "gender_distribution": [
                {
                  "gender": "MALE",
                  "percentage": "0.349"
                }
              ],
              "type": "VIEWERS"
            }
          ]
        },
        "video": {
          "duration": 10,
          "id": "7523456789012345678",
          "play_url": "`https://example.com/video.mp4`",
          "thumbnail_url": "`https://example.com/thumbnail.jpg`",
          "title": "`Summer collection`",
          "username": "`shop_creator`",
          "video_post_time": "1725148800"
        },
        "video_id": "7523456789012345678"
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}
DocsSDKsAPI Reference

Start here

Getting StartedConceptsAuthorizationWebhooksErrors

SDKs

Choose an SDK

OpenAPI

The spec