Developer resources

Get ad benchmarks — TikTok Business API

Get ad benchmarks · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

Open in the API index TikTok Business platform page

Get ad benchmarks

GET/report/ad_benchmark/get/Via 360: GET https://partner.quantri360.com/v1/tiktok_business/report/ad_benchmark/get/

Description

Use this endpoint to get the performance data of ads against benchmarks.

> Note

All data returned via this endpoint has a latency of 30-48 hours.

Request

Endpoint

GET https://partner.quantri360.com/v1/tiktok_business/report/ad_benchmark/get/

Authentication & shop

Name	In	Type	Sample	Description
Authorization	header	header	Bearer q360_live_ab12cd34_…	Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_id	query	string	7000000000000000001	Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản.

Request parameters

Name	In	Type	Required	Description
compare_time_window	query	string	No	Time window for comparison (in days). Enum: `7` (default), `14`, `30`, `60`
dimensions	query	string[]	Yes	List of dimensions to compare. 1-4 dimensions are allowed. Enum: `LOCATION`, `AD_CATEGORY`, `EXTERNAL_ACTION`, `PLACEMENT`
metrics_fields	query	string[]	No	Metrics that you want to get. By default, all metrics will be returned. See the Supported metrics section for supported metrics.
filtering	query	object	Yes	Filtering conditions. You must specify one and only one out of the three conditions allowed
sort_field	query	string	No	Field to sort by. By default, results will be sorted by `CREATE_TIME`
sort_type	query	string	No	Sorting type. Enum: `ASC` (starting from the one that was created earliest), `DES` (starting from the one that was created latest)
page	query	number	No	Page number
page_size	query	number	No	Page size

Request examples

curl -s "https://partner.quantri360.com/v1/tiktok_business/report/ad_benchmark/get/?dimensions=%5B%5D&filtering=%7B%7D" \
  -H "Authorization: Bearer $KEY"

Python

import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.get(
    "https://partner.quantri360.com/v1/tiktok_business/report/ad_benchmark/get/",
    params={
        "dimensions": [],
        "filtering": {}
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())

Node.js

const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok_business/report/ad_benchmark/get/');
for (const [k, v] of Object.entries({"dimensions":[],"filtering":{}})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'GET',
  headers: { Authorization: `Bearer ${KEY}` },
});
console.log(r.status, await r.json());

PHP

<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok_business/report/ad_benchmark/get/' . '?' . http_build_query(['dimensions' => '[]', 'filtering' => '{}']);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Response fields (as returned by TikTok Business)

Name	Type	Description
code	number	Response code. For the complete list of error codes and descriptions, see Appendix - Return Codes.
message	string	Response message. For details, see Appendix - Return Codes.
request_id	string	Unique ID of the request
data	object	Returned data
compare_date	string	Date when the comparison is performed
list	object	List of results. Note: If an ad accumulates fewer than 1,000 impressions within the comparison window (`compare_time_window`), the benchmark metric data will be empty.
info	object	Information about the subject to get benchmark data for
ad_id	string	Ad ID
location	string	Two-letter country or region code
placement	string	Placement
ad_category	number	Level 2 interest category ID. For the list of categories, see Get interest categories. To determine the corresponding names for gaming-related interest category IDs, see Interest category.
external_action	string	External action (conversion event) for the ad
metrics	object	Metrics and values
metric_name	number	The returned metrics, determined by the setting via `metrics_fields` in the request. After the metric name, you can see a number with one decimal place, in the value range of [0.0,1.0]. The number indicates how the current metric of the ad performs compared with other ads in terms of dimensions (`dimensions`) you specify in the request. For instance, `"video_watched_6s": 0.6` means the "video_watched_6s" metric data of the ad outperforms about 60% of all ads in terms of specified dimensions. See the Supported metrics section for the supported metrics.
page_info	object	Pagination information
page	number	Current page number
total_page	number	Total number of pages
page_size	number	Page size. Default: 10
total_number	number	Total number of results

Response sample

HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "2021120912121801024524603910501234",
    "data": {
        "compare_date": "2021-12-05",
        "list": [
            {
                "info": {
                    "placement": "TIKTOK",
                    "ad_id": "1234943678835714",
                    "location": "VN",
                    "ad_category": "0",
                    "external_action": "FORM_BUTTON"
                },
                "metrics": {
                    "video_watched_6s": 0.6,
                    "video_views_p25": 0.4,
                    "click": 0.8,
                    "video_views_p100": 0.4,
                    "average_video_play": 0.2,
                    "video_views_p50": 0.4,
                    "cpm": 0.1,
                    "profile_visits_rate": 0.9,
                    "cost": 0.7,
                    "impression": 0.8,
                    "cpa": 0.8,
                    "video_views_p75": 0.4,
                    "cpv": 0.0,
                    "cpc": 0.1,
                    "cvr": 0.2,
                    "ctr": 0.4,
                    "video_watched_2s": 0.7,
                    "pvr": 0.2,
                    "conversion": 0.6,
                    "video_views": 0.8
                }
            },
            {
                "info": {
                    "ad_id": "1234003068951586"
                }
            }
        ],
        "page_info": {
            "page": 1,
            "total_page": 1,
            "page_size": 10,
            "total_number": 2
        }
    }
}
(/code);

Get started

Sign up for Partner
Enable a data type of the Ads (Marketing API) group on the platform page
Create an API key (tick the TikTok Business channel)
Call it as in the examples above