Developer resources

Get catalog event trends and match rate — TikTok Business API

Get catalog event trends and match rate · 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 catalog event trends and match rate

GET/diagnostic/catalog/eventsource/metric/Via 360: GET https://partner.quantri360.com/v1/tiktok_business/diagnostic/catalog/eventsource/metric/

Description

Use this endpoint to retrieve the trend of app events or pixel events received, identify the number of events available for retargeting, and obtain the catalog match rate of your catalog.

Request

Endpoint

GET https://partner.quantri360.com/v1/tiktok_business/diagnostic/catalog/eventsource/metric/

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
bc_id	query	string	Yes	Business Center ID. To get the list of Business Centers that you can access, use /bc/get/.
catalog_id	query	string	Yes	Catalog ID. To get the catalogs under a Business Center, use /catalog/get/.
event_source_type	query	string	Yes	The event source type. Enum values: - `APP`: App. Pass `app_id` at the same time. - `PIXEL`: Pixel. Pass `pixel_code` at the same time.
pixel_code	query	string	No	Required when `event_source_type` is set to `PIXEL`. The Pixel code. To retrieve the Pixel codes that are bound to your catalog (`catalog_id`), use /catalog/eventsource_bind/get/..
event_type	query	string	No	The event type that you want to retrieve data for. Enum values: - `VIEW_CONTENT`: View Content. - `ADD_TO_CART`: Add to Cart. - `PURCHASE`: Complete Payment. Default value: `VIEW_CONTENT`.
time_range	query	string	No	The time range that you want to retrieve data for. Enum values: - `YESTERDAY`: Yesterday. - `LAST_7_DAYS`: Last 7 days. - `LAST_30_DAYS`: Last 30 days. Default value: `LAST_7_DAYS`.

Request examples

curl -s "https://partner.quantri360.com/v1/tiktok_business/diagnostic/catalog/eventsource/metric/?bc_id=&catalog_id=&event_source_type=" \
  -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/diagnostic/catalog/eventsource/metric/",
    params={
        "bc_id": "",
        "catalog_id": "",
        "event_source_type": ""
    },
    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/diagnostic/catalog/eventsource/metric/');
for (const [k, v] of Object.entries({"bc_id":"","catalog_id":"","event_source_type":""})) 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/diagnostic/catalog/eventsource/metric/' . '?' . http_build_query(['bc_id' => '', 'catalog_id' => '', 'event_source_type' => '']);
$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 response codes and descriptions, see Appendix-Return Code.
message	string	Response message. For details, see Appendix - Return Codes.
request_id	string	The log ID of a request, which uniquely identifies the request.
data	object	Returned data.
list	object[]	Information about the trend of events received and the number of events available for retargeting.
available_type	string	The available categories of events. Enum values: - `EVENT_RECEIVED`: All events. - `EVENT_WITH_CONTENT_ID`: Events with content IDs. - `EVENT_WITH_CONTENT_ID_MATCHING_INVENTORY`: Events matching content IDs (Events with content IDs that match inventory).
event_details	object[]	The details of the event category (`available_type`).
date	string	The date, in the format of `"YYYY-MM-DD"`. Example: `"2023-12-30"`.
count	string	The number of events that belong to the event category are received on the date. Example: `"245076"`. For instance, when `available_type` is `EVENT_WITH_CONTENT_ID_MATCHING_INVENTORY`, a value of `"245076"` for this field represents that 245,076 events with content IDs that match products (SKU ID) in your catalog are received on the date.
percentage	string	The percentage of the events belonging to the event category that are received on the date, out of all events received on the date. When `available_type` is `EVENT_WITH_CONTENT_ID_MATCHING_INVENTORY`, the value of this field represents the catalog match rate, which is calculated by dividing the number of signal events that match products in your catalog by the total number of signal events shared with TikTok. We recommend keeping your match rate levels above 90% to ensure optimal ad performance for Video Shopping Ads. Example: `"100"`. Note: When `available_type` is `EVENT_RECEIVED`, the value of this field is always `"100"`.

Response sample

HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "list": [
            {
                "available_type": "EVENT_RECEIVED",
                "event_details": [
                    {
                        "date": "2023-10-04",
                        "percentage": "100",
                        "count": "4086"
                    },
                    {
                        "date": "2023-10-05",
                        "percentage": "100",
                        "count": "4372"
                    },
                    {
                        "date": "2023-10-06",
                        "percentage": "100",
                        "count": "3939"
                    },
                    {
                        "date": "2023-10-07",
                        "percentage": "100",
                        "count": "3017"
                    },
                    {
                        "date": "2023-10-08",
                        "percentage": "100",
                        "count": "2853"
                    },
                    {
                        "date": "2023-10-09",
                        "percentage": "100",
                        "count": "5197"
                    },
                    {
                        "date": "2023-10-10",
                        "percentage": "100",
                        "count": "5050"
                    }
                ]
            },
            {
                "available_type": "EVENT_WITH_CONTENT_ID",
                "event_details": [
                    {
                        "date": "2023-10-04",
                        "percentage": "96",
                        "count": "3960"
                    },
                    {
                        "date": "2023-10-05",
                        "percentage": "97",
                        "count": "4259"
                    },
                    {
                        "date": "2023-10-06",
                        "percentage": "97",
                        "count": "3847"
                    },
                    {
                        "date": "2023-10-07",
                        "percentage": "96",
                        "count": "2899"
                    },
                    {
                        "date": "2023-10-08",
                        "percentage": "95",
                        "count": "2728"
                    },
                    {
                        "date": "2023-10-09",
                        "percentage": "96",
                        "count": "5035"
                    },
                    {
                        "date": "2023-10-10",
                        "percentage": "97",
                        "count": "4908"
                    }
                ]
            },
            {
                "available_type": "EVENT_WITH_CONTENT_ID_MATCHING_INVENTORY",
                "event_details": [
                    {
                        "date": "2023-10-04",
                        "percentage": "37",
                        "count": "1535"
                    },
                    {
                        "date": "2023-10-05",
                        "percentage": "35",
                        "count": "1572"
                    },
                    {
                        "date": "2023-10-06",
                        "percentage": "36",
                        "count": "1450"
                    },
                    {
                        "date": "2023-10-07",
                        "percentage": "33",
                        "count": "1019"
                    },
                    {
                        "date": "2023-10-08",
                        "percentage": "28",
                        "count": "819"
                    },
                    {
                        "date": "2023-10-09",
                        "percentage": "37",
                        "count": "1946"
                    },
                    {
                        "date": "2023-10-10",
                        "percentage": "36",
                        "count": "1867"
                    }
                ]
            }
        ]
    }
}

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