TikTok AdsTikTok AdsAdvertising

Your TikTok ads' spend, impressions, clicks, conversions

tiktok-ads.query

Get spend, impressions, clicks and conversions for your TikTok ads

Price: freeAt provider cost
Success rate: —No success-rate data yetNo success-rate data yet
Latency p50: ——
Last verified: —Not verified yet

GEThttps://toolswitch.dev/v1/tools/tiktok-ads.queryPreview

Uses platform quota
Synchronous response
Reads public data

Parameters

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

Parameter	Type	Required	Description	Example
Query parameters
`page`	integer	Optional		`1`
`metrics`	array	Optional	JSON array; defaults to a thin set, so always name them	`["spend","impressions","clicks","ctr","cpc","conversion","cost_per_conversion"]`
`end_date`	string	Optional	YYYY-MM-DD; the window is capped (about 30 days for most report types)	`2026-07-28`
`filtering`	array	Optional	JSON array of filter objects, e.g. [{"field_name":"campaign_ids","filter_type":"IN","filter_value":"[\"123\"]"}]
`page_size`	integer	Optional	max 1000, default 200	`100`
`data_level`	string	Required	AUCTION_ADVERTISER \| AUCTION_CAMPAIGN \| AUCTION_ADGROUP \| AUCTION_AD — must match the id dimension you ask for	`AUCTION_CAMPAIGN`
`dimensions`	array	Required	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`	string	Optional	ASC \| DESC	`DESC`
`start_date`	string	Optional	YYYY-MM-DD, in the advertiser's timezone; required unless query_lifetime is true	`2026-06-28`
`order_field`	string	Optional		`spend`
`report_type`	string	Required	BASIC (performance) \| AUDIENCE (demographic breakdowns) \| PLAYABLE_MATERIAL \| CATALOG \| BC	`BASIC`
`advertiser_id`	string	Required		`7000000000000000000`
`query_lifetime`	boolean	Optional	true returns all-time totals and forbids start_date/end_date	`false`

Query parameters
pageintegerOptional
Example: 1
metricsarrayOptional
JSON array; defaults to a thin set, so always name them
Example: ["spend","impressions","clicks","ctr","cpc","conversion","cost_per_conversion"]
end_datestringOptional
YYYY-MM-DD; the window is capped (about 30 days for most report types)
Example: 2026-07-28
filteringarrayOptional
JSON array of filter objects, e.g. [{"field_name":"campaign_ids","filter_type":"IN","filter_value":"[\"123\"]"}]
page_sizeintegerOptional
max 1000, default 200
Example: 100
data_levelstringRequired
AUCTION_ADVERTISER | AUCTION_CAMPAIGN | AUCTION_ADGROUP | AUCTION_AD — must match the id dimension you ask for
Example: AUCTION_CAMPAIGN
dimensionsarrayRequired
JSON array in the query string. One id dimension plus optionally stat_time_day for a daily series: ["campaign_id","stat_time_day"]
Example: ["campaign_id","stat_time_day"]
order_typestringOptional
ASC | DESC
Example: DESC
start_datestringOptional
YYYY-MM-DD, in the advertiser's timezone; required unless query_lifetime is true
Example: 2026-06-28
order_fieldstringOptional
Example: spend
report_typestringRequired
BASIC (performance) | AUDIENCE (demographic breakdowns) | PLAYABLE_MATERIAL | CATALOG | BC
Example: BASIC
advertiser_idstringRequired
Example: 7000000000000000000
query_lifetimebooleanOptional
true returns all-time totals and forbids start_date/end_date
Example: false

Code samples

Replace $TOOLSWITCH_KEY with the key you created in the console.

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());

This gateway API is in preview; its URL and authentication may change. The example parameters are sample data. Calls are billed at free, including the service fee.