TikTok AdsTikTok AdsAdvertising

Your TikTok ads' spend, impressions, clicks, conversions

tiktok-ads.query

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

Price: freeZum Anbieterpreis
Success rate: —Noch keine ErfolgsratendatenNoch keine Erfolgsratendaten
Latency p50: ——
Last verified: —Not verified yet

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

Uses platform quota
Synchronous response
Reads public data

Parameter

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	Typ	Erforderlich	Beschreibung	Beispiel
Abfrageparameter
`page`	Ganzzahl	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`	Zeichenkette	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`	Ganzzahl	Optional	max 1000, default 200	`100`
`data_level`	Zeichenkette	Erforderlich	AUCTION_ADVERTISER \| AUCTION_CAMPAIGN \| AUCTION_ADGROUP \| AUCTION_AD — must match the id dimension you ask for	`AUCTION_CAMPAIGN`
`dimensions`	Array	Erforderlich	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`	Zeichenkette	Optional	ASC \| DESC	`DESC`
`start_date`	Zeichenkette	Optional	YYYY-MM-DD, in the advertiser's timezone; required unless query_lifetime is true	`2026-06-28`
`order_field`	Zeichenkette	Optional		`spend`
`report_type`	Zeichenkette	Erforderlich	BASIC (performance) \| AUDIENCE (demographic breakdowns) \| PLAYABLE_MATERIAL \| CATALOG \| BC	`BASIC`
`advertiser_id`	Zeichenkette	Erforderlich		`7000000000000000000`
`query_lifetime`	Boolean	Optional	true returns all-time totals and forbids start_date/end_date	`false`

Abfrageparameter
pageGanzzahlOptional
Beispiel: 1
metricsArrayOptional
JSON array; defaults to a thin set, so always name them
Beispiel: ["spend","impressions","clicks","ctr","cpc","conversion","cost_per_conversion"]
end_dateZeichenketteOptional
YYYY-MM-DD; the window is capped (about 30 days for most report types)
Beispiel: 2026-07-28
filteringArrayOptional
JSON array of filter objects, e.g. [{"field_name":"campaign_ids","filter_type":"IN","filter_value":"[\"123\"]"}]
page_sizeGanzzahlOptional
max 1000, default 200
Beispiel: 100
data_levelZeichenketteErforderlich
AUCTION_ADVERTISER | AUCTION_CAMPAIGN | AUCTION_ADGROUP | AUCTION_AD — must match the id dimension you ask for
Beispiel: AUCTION_CAMPAIGN
dimensionsArrayErforderlich
JSON array in the query string. One id dimension plus optionally stat_time_day for a daily series: ["campaign_id","stat_time_day"]
Beispiel: ["campaign_id","stat_time_day"]
order_typeZeichenketteOptional
ASC | DESC
Beispiel: DESC
start_dateZeichenketteOptional
YYYY-MM-DD, in the advertiser's timezone; required unless query_lifetime is true
Beispiel: 2026-06-28
order_fieldZeichenketteOptional
Beispiel: spend
report_typeZeichenketteErforderlich
BASIC (performance) | AUDIENCE (demographic breakdowns) | PLAYABLE_MATERIAL | CATALOG | BC
Beispiel: BASIC
advertiser_idZeichenketteErforderlich
Beispiel: 7000000000000000000
query_lifetimeBooleanOptional
true returns all-time totals and forbids start_date/end_date
Beispiel: false

Codebeispiele

Ersetze $TOOLSWITCH_KEY durch den in der Konsole erstellten Schlüssel.

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

Diese Gateway-API ist eine Vorschauversion; URL und Authentifizierung können sich ändern. Die Beispielparameter sind Musterdaten. Aufrufe werden mit free einschließlich Servicegebühr abgerechnet.