Your TikTok ads' spend, impressions, clicks, conversions
tiktok-ads.queryGet spend, impressions, clicks and conversions for your TikTok ads
- 价格
- free按供应商原价
- 成功率
- —暂无成功率数据暂无成功率数据
- 延迟 p50
- ——
- 最后验证
- —尚未验证
GEThttps://toolswitch.dev/v1/tools/tiktok-ads.query预览- 可用平台额度调用
- 同步返回
- 读取公开数据
参数
spend is a decimal STRING in the advertiser's currency (not micros). Dimensions and metrics are validated as a pair: asking for a metric the chosen data_level does not support fails the whole request with code 40002 instead of dropping the column. Attribution follows the ad account's window, so today's conversions keep changing for days
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| 查询参数 | ||||
page | 整数 | 可选 | 1 | |
metrics | 数组 | 可选 | JSON array; defaults to a thin set, so always name them | ["spend","impressions","clicks","ctr","cpc","conversion","cost_per_conversion"] |
end_date | 字符串 | 可选 | YYYY-MM-DD; the window is capped (about 30 days for most report types) | 2026-07-28 |
filtering | 数组 | 可选 | JSON array of filter objects, e.g. [{"field_name":"campaign_ids","filter_type":"IN","filter_value":"[\"123\"]"}] | |
page_size | 整数 | 可选 | max 1000, default 200 | 100 |
data_level | 字符串 | 必填 | AUCTION_ADVERTISER | AUCTION_CAMPAIGN | AUCTION_ADGROUP | AUCTION_AD — must match the id dimension you ask for | AUCTION_CAMPAIGN |
dimensions | 数组 | 必填 | JSON array in the query string. One id dimension plus optionally stat_time_day for a daily series: ["campaign_id","stat_time_day"] | ["campaign_id","stat_time_day"] |
order_type | 字符串 | 可选 | ASC | DESC | DESC |
start_date | 字符串 | 可选 | YYYY-MM-DD, in the advertiser's timezone; required unless query_lifetime is true | 2026-06-28 |
order_field | 字符串 | 可选 | spend | |
report_type | 字符串 | 必填 | BASIC (performance) | AUDIENCE (demographic breakdowns) | PLAYABLE_MATERIAL | CATALOG | BC | BASIC |
advertiser_id | 字符串 | 必填 | 7000000000000000000 | |
query_lifetime | 布尔 | 可选 | true returns all-time totals and forbids start_date/end_date | false |
- 查询参数
page整数可选示例：
1metrics数组可选JSON array; defaults to a thin set, so always name them
示例：
["spend","impressions","clicks","ctr","cpc","conversion","cost_per_conversion"]end_date字符串可选YYYY-MM-DD; the window is capped (about 30 days for most report types)
示例：
2026-07-28filtering数组可选JSON array of filter objects, e.g. [{"field_name":"campaign_ids","filter_type":"IN","filter_value":"[\"123\"]"}]
page_size整数可选max 1000, default 200
示例：
100data_level字符串必填AUCTION_ADVERTISER | AUCTION_CAMPAIGN | AUCTION_ADGROUP | AUCTION_AD — must match the id dimension you ask for
示例：
AUCTION_CAMPAIGNdimensions数组必填JSON array in the query string. One id dimension plus optionally stat_time_day for a daily series: ["campaign_id","stat_time_day"]
示例：
["campaign_id","stat_time_day"]order_type字符串可选ASC | DESC
示例：
DESCstart_date字符串可选YYYY-MM-DD, in the advertiser's timezone; required unless query_lifetime is true
示例：
2026-06-28order_field字符串可选示例：
spendreport_type字符串必填BASIC (performance) | AUDIENCE (demographic breakdowns) | PLAYABLE_MATERIAL | CATALOG | BC
示例：
BASICadvertiser_id字符串必填示例：
7000000000000000000query_lifetime布尔可选true returns all-time totals and forbids start_date/end_date
示例：
false
代码示例
将 $TOOLSWITCH_KEY 替换为你在控制台创建的密钥。
curl -X GET 'https://toolswitch.dev/v1/tools/tiktok-ads.query' \
-H "X-Toolswitch-Key: $TOOLSWITCH_KEY"import os
import requests
response = requests.request(
"GET",
"https://toolswitch.dev/v1/tools/tiktok-ads.query",
headers={"X-Toolswitch-Key": os.environ["TOOLSWITCH_KEY"]},
)
response.raise_for_status()
print(response.text)const response = await fetch("https://toolswitch.dev/v1/tools/tiktok-ads.query", {
method: "GET",
headers: {
"X-Toolswitch-Key": process.env.TOOLSWITCH_KEY ?? "",
},
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
console.log(await response.text());网关接口为预览版，地址与鉴权方式可能调整。 示例参数仅为样例数据。 调用按 free 计费，已含服务费。