Your TikTok ads' spend, impressions, clicks, conversions
tiktok-ads.queryGet spend, impressions, clicks and conversions for your TikTok ads
- Price
- freeプロバイダー原価
- Success rate
- —成功率データはまだありません成功率データはまだありません
- Latency p50
- ——
- Last verified
- —Not verified yet
GEThttps://toolswitch.dev/v1/tools/tiktok-ads.queryPreview- Uses platform quota
- Synchronous response
- Reads public data
パラメータ
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());このゲートウェイ API はプレビュー版です。URL や認証方式は変更される場合があります。 パラメータはサンプルデータです。 呼び出し料金は free です。サービス料を含みます。