Create an asynchronous report task
POST/report/task/create/Via 360: POST https://partner.quantri360.com/v1/tiktok_business/report/task/create/
Write endpoint — changes data on TikTok Business. The key must be created with "Allow write API calls" ticked, otherwise you get 403 write_not_allowed. Every call is logged.
Description
Use this endpoint to create an asynchronous report task.
See Run an asynchronous report to learn about how to run an asynchronous report.
You can use different endpoints to create a standard (synchronous) report and an asynchrounous report. To find out the supported dimensions, metrics, and use cases for different report types, see Report types. Also, you need to use POST method for asynchronous reports and GET method for standard (synchronous) reports.
Request
Endpoint
POST https://partner.quantri360.com/v1/tiktok_business/report/task/create/
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 | Sample | Description |
|---|---|---|---|---|---|
| advertiser_ids | body | string[] | No | Either advertiser_id or advertiser_ids has to be set. If you pass in both advertiser_id and advertiser_ids, advertiser_id will be ignored.
A list of advertiser IDs.
Max size: 5.
Note:
- This field is only valid when report_type is BASIC or AUDIENCE.
- The advertisers specified in advertiser_ids should all belong to the same TikTok for Business user. Otherwise, an error will occur. Use /oauth2/advertiser/get/ to retrieve a list of advertiser IDs that belong to the same TikTok for Business user.
- If you specify start_date and end_date at the same time, the data will be pulled according to the timezone of each ad account.
- When you pass multiple advertiser IDs, you can specify up to two ID dimensions (advertiser_id + another ID dimension) in dimensions. However, many metrics do not support the advertiser_id dimension. Also, it's recommended that you include currency in metrics, because the ad accounts may have different currencies. | |
| service_type | body | string | No | Ad service type.
Enum values:
- AUCTION: auction ads, or both auction ads and reservation ads.
- RESERVATION (deprecated) : reservation ads. Default value: AUCTION.
Note: To retrieve the reporting data of TopView ads, use the basic reports or audience reports and specify the value RESERVATION_TOP_VIEW for the buying_type filter. | |
| report_type | body | string | Yes | Report type.
Enum values: BASIC (basic report), AUDIENCE (audience report), PLAYABLE_MATERIAL (playable ads report), CATALOG (DSA report).
When service_type is AUCTION, BASIC, AUDIENCE, PLAYABLE_MATERIAL, and CATALOG reports are all supported.
Note: You can retrieve the creative level data for Upgraded Smart+ Ads when report_type is BASIC, AUDIENCE, or CATALOG. | |
| data_level | body | string | No | The data level that you'd like to query in reports. Required when report_type is BASIC,AUDIENCE or CATALOG.
Enum values:
- AUCTION_AD: auction ads or both auction ads and reservation ads, ad level.
- AUCTION_ADGROUP: auction ads or both auction ads and reservation ads, ad group level.
- AUCTION_CAMPAIGN: auction ads or both auction ads and reservation ads, campaign level.
- AUCTION_ADVERTISER: auction ads or both auction ads and reservation ads, advertiser level.
- RESERVATION_AD(deprecated): reservation ads, ad level.
- RESERVATION_ADGROUP(deprecated): reservation ads, ad group level.
- RESERVATION_CAMPAIGN(deprecated): reservation ads, campaign level.
- RESERVATION_ADVERTISER(deprecated): reservation ads, advertiser level. | |
| dimensions | body | string[] | Yes | Grouping conditions. For example: ["campaign_id", "stat_time_day"] indicates that both campaign_id and stat_time_day (days) are grouped.
Different report types support different dimensions.
- Supported dimensions in basic reports
- Supported dimensions in audience reports
- Supported dimensions in playable ad reports
- Supported dimensions in DSA reports
- Supported dimensions in Business Center reports
Note :
- Different report types support different dimensions. For supported dimensions for each report type, see the corresponding articles under Report types.
- If your query dimensions contain more than xx_id and there is no ads reporting within the query time range, an empty list will be returned.
- The dimension and metric combinations that are supported may vary between synchronous and asynchronous reports. Therefore, a valid dimension and metric combination in synchronous reports may not be supported in asynchronous reports.
- The dimension ad_id_v2 is available. Note that:
- You need to ensure the report_type is BASIC, AUDIENCE, or CATALOG.
- You cannot use it together with the dimension ad_id or the filter ad_ids.
- The types of data you can get include:
- the ad level data for Manual Ads.
- the ad level data for Smart+ Campaigns.
- the ad level data for Upgraded Smart+ Ads. | |
| metrics | body | string[] | No | Metrics to query.
Different report types support different metrics. For supported metrics for each report type, see the corresponding articles under Report types.
Default value: ["spend", "impressions"]. | |
| start_date | body | string | No | This field is required when query_lifetime is false or not specified.
Query start date (closed interval) in the format of YYYY-MM-DD. The date is based on the ad account time zone.
Note: Asynchronous reports have no time range limitations. | |
| end_date | body | string | No | This field is required when query_lifetime is false or not specified.
Query end date (closed interval) in the format of YYYY-MM-DD. The date is based on the ad account time zone.
Note: Asynchronous reports have no time range limitations. | |
| query_lifetime | body | boolean | No | Whether to request the lifetime metrics.
Default value: false.
If query_lifetime = true, the start_date and end_date parameters will be ignored. The lifetime metric name is the same as the normal one.
Note:
- Breakdown by time or audience is not supported when querying for lifetime metrics.
- Breakdown by location code (country_code) is not supported when querying for lifetime metrics.
- DSA reports do not support lifetime metrics. Besides, Audience reports do not support lifetime metrics at the time, and will support lifetime metrics in the first half of 2023. | |
| order_field | body | string | No | Sorting field. All supported metrics (excluding attribute metrics) support sorting. Not sorting by default. | |
| order_type | body | string | No | Sorting order.
Enum values: ASC, DESC.
Default value: DESC. | |
| enable_report_title_translation | body | boolean | No | Whether to enable the translation of the title row of the asynchronous report (including dimension names and metric names).
For instance, if this field is set to false, a report title can be ad_id (untranslated title) rather than AD ID (translated title).
Default value: true.
Note:
- This field is only valid when report_type is BASIC or AUDIENCE.
- Starting November 15th, 2024, the translation of certain metrics in the title row of async reports will be updated to provide a better user experience. This change will not affect the metric field names themselves. To minimize potential disruptions, we strongly recommend setting enable_report_title_translation to false in your code. This will eliminate dependencies on metric translations, which are subject to periodic updates. While these translations are provided to help map metrics to their corresponding names in TikTok Ads Manager, relying on them in your code may lead to breaking changes in the future. By disabling title row translation, you can ensure more stable and predictable behavior in your integration. | |
| output_format | body | string | No | Format of output.
Enum values: CSV_STRING, CSV_DOWNLOAD, XLSX_DOWNLOAD.
Default value: CSV_STRING. | |
| file_name | body | string | No | Customized download file name, which is optional to pass when output_format is CSV_DOWNLOAD or XLSX_DOWNLOAD. The maximum length is 255 characters. The file name needs to exclude the following special characters: ['/', '\t', '\b', '@', '#', '$', '%', '^', '&', '*', '(', ')', '[', ']']. | |
| filtering | body | object[] | No | Filtering conditions. Supported filtering conditions vary based on service_type and data_level.
Note:
- When you pass in filtering, please make sure you specify the fields field_name, filter_type, and filter_value at the same time as an object in a list.
- If you want to use country_code as your grouping filter, then please specify country_code in the dimensions field of the request. Note that country_code works with basic report (sync and async), audience report (sync and async), and playable ad report (sync only).
- In asynchronous mode for the report types of basic reports, audience reports, and DSA reports, the only supported filter fields are campaign_ids, adgroup_ids, and ad_ids. |
Request examples
curl -s -X POST "https://partner.quantri360.com/v1/tiktok_business/report/task/create/" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"report_type":"","dimensions":[],"filtering":[{}]}'
Python
import requests
KEY = "q360_live_..." # khóa API của brand
r = requests.post(
"https://partner.quantri360.com/v1/tiktok_business/report/task/create/",
params={},
json={
"report_type": "",
"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/task/create/');
for (const [k, v] of Object.entries({})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({"report_type":"","dimensions":[],"filtering":[{}]}),
});
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/task/create/' . '?' . http_build_query([]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key, 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"report_type":"","dimensions":[],"filtering":[{}]}');
$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 | Sample | Description |
|---|---|---|---|
| code | number | The response code. For the complete list of response codes and descriptions, see Appendix - Return Codes. | |
| message | string | The response message. For details, see Appendix - Return Codes. | |
| data | object | The returned data. | |
| task_id | string | The ID of the asynchronous report task. | |
| request_id | string | The unique ID of the request. |
Response sample
HTTPS/1.1 200 OK
{
"message": "OK",
"code": 0,
"data": {
"task_id": "{{task_id}}"
},
"request_id": "{{request_id}}"
}
(/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