TikTok AdsTikTok AdsAdvertising

Your TikTok ads' spend, impressions, clicks, conversions

tiktok-ads.query

Get 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정수선택
예시: 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

코드 예제

$TOOLSWITCH_KEY를 콘솔에서 생성한 키로 바꾸세요.

Preview

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이며 서비스 수수료가 포함되어 있습니다.