VI | EN
Message us on Messenger
Developer resources

Get Creative Fatigue Detection results — TikTok Business API

Get Creative Fatigue Detection results · 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.

Get Creative Fatigue Detection results

GET/creative_fatigue/get/Via 360: GET https://partner.quantri360.com/v1/tiktok_business/creative_fatigue/get/
Description

Use this endpoint to detect whether Creative Fatigue occurred for creatives within a specified time range in the past.

To find out a detailed introduction of the Creative Fatigue Detection feature, see here.

> Important

> This endpoint has been completely revamped with an updated schema. Review the new schema details below to successfully migrate your existing integration.

Request

Endpoint

GET https://partner.quantri360.com/v1/tiktok_business/creative_fatigue/get/

Authentication & shop

NameInTypeSampleDescription
AuthorizationheaderheaderBearer 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_idquerystring7000000000000000001Tà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

NameInTypeRequiredSampleDescription
ad_idquerystringNoThe ID of the ad that you want to get Creative Fatigue detection results for.
adgroup_idquerystringYesAd group ID. To obtain ad group IDs, use /smart_plus/adgroup/get/.
ad_material_idsquerystring[]YesA list of ad material IDs for creatives to operate on. An ad material ID is an ad-specific material ID generated when a particular creative is used in an ad. This ID differs from the creative ID you receive when uploading the creative to your ad account’s Creative Library. Max size: 100. To obtain ad material IDs associated with an ad, use /smart_plus/ad/get/. Note: For images within a carousel, you need to provide the ad_material_id from /smart_plus/ad/review_info/, not the one from /smart_plus/ad/get/ which identifies the entire carousel.
filteringqueryobjectYesFiltering conditions.
pagequerynumberNoCurrent page number. Default value: 1. Value range: ≥ 1.
page_sizequerynumberNoPage size. Default value: 10. Value range: [1, 500].

Request examples

curl -s "https://partner.quantri360.com/v1/tiktok_business/creative_fatigue/get/?adgroup_id=&ad_material_ids=%5B%5D&filtering=%7B%22start_date%22%3A%22%22%2C%22end_date%22%3A%22%22%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/creative_fatigue/get/",
    params={
        "adgroup_id": "",
        "ad_material_ids": [],
        "filtering": {
            "start_date": "",
            "end_date": ""
        }
    },
    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/creative_fatigue/get/');
for (const [k, v] of Object.entries({"adgroup_id":"","ad_material_ids":[],"filtering":{"start_date":"","end_date":""}})) 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/creative_fatigue/get/' . '?' . http_build_query(['adgroup_id' => '', 'ad_material_ids' => '[]', 'filtering' => '{"start_date":"","end_date":""}']);
$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)

NameTypeSampleDescription
codenumberResponse code. For the complete list of response codes and descriptions, see Appendix-Return Code.
messagestringResponse message. For details, see Appendix - Return Codes.
request_idstringThe log ID of a request, which uniquely identifies the request.
dataobjectReturned data.
listobject[]Information about the Creative Fatigue detection results.
adgroup_idstringID of the ad group.
ad_idstringID of the ad.
datestringThe date for which the values of the `metrics` are retrieved.
metricsobject[]Information about data of the metrics on the date (`date`).
ad_material_idstringAn ad material ID is an ad-specific material ID generated when a creative is used in an ad.
has_fatiguebooleanWhether Creative Fatigue is detected. Supported values: `true`, `false`.
spendnumberTotal cost, which is the estimated total amount of money spent on the ad, in the default currency for the ad account.
cost_per_conversionnumberCPA, which is the average amount of money spent on a conversion from the ad, in the default currency for the ad account. The total count is calculated based on the time each ad impression occurred.
metricsobjectInformation about data of the metrics on the date (`date`).
has_fatiguebooleanWhether Creative Fatigue is detected.
fatigue_indexnumberThe "Fatigue Index" is a comprehensive metric that considers day-over-day changes in CPA, cost, the new users reach rate, and other performance metrics. A higher index value indicates a greater degree of fatigue.
dnunumberDNU. The number of daily new users that the ad attracts.
dnu_rationumberDNU ratio. This metric is calculated by dividing the number of daily new users attracted by the ad on a specific date by the maximum number of daily new users that the ad attracted in the last 60 days.
spendnumberTotal cost, which is the estimated total amount of money you've spent on the ad, in the default currency for the ad account.
cost_per_conversionnumberThis metric returns actual value when the ad is within a non-iOS 14 Dedicated Campaign, and returns `0.0` when the ad is within an iOS 14 Dedicated Campaign. You can check whether a campaign is an iOS 14 Dedicated Campaign via the value of `campaign_type` returned by /campaign/get/. CPA, which is the average amount of money spent on a conversion from the ad, in the default currency for the ad account. The total count is calculated based on the time each ad impression occurred.
skan_cost_per_conversionnumberThis metric returns actual value when the ad is within an iOS 14 Dedicated Campaign, and returns `0.0` when the ad is within a non-iOS 14 Dedicated Campaign. You can check whether a campaign is an iOS 14 Dedicated Campaign via the value of `campaign_type` returned by /campaign/get/. CPA (SKAN), the average amount of money spent on a conversion from the ad, in the default currency for the ad account. The total count is based on when the events are returned through the SKAdNetwork API. There may be a delay between the actual conversion time and when the conversion is reported.
page_infoobjectPagination information.
pagenumberCurrent page number.
page_sizenumberCurrent page size.
total_numbernumberTotal number of results.
total_pagenumberTotal number of pages.

Response sample

{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "list": [],
        "page_info": {
            "page": 1,
            "page_size": 10,
            "total_number": 0,
            "total_page": 0
        }
    }
}

Get started

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