TikTok AdsTikTok AdsAdvertising

Your TikTok ads' spend, impressions, clicks, conversions

tiktok-ads.query

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

Price: freeAu prix du fournisseur
Success rate: —Aucune donnée de taux de réussite pour le momentAucune donnée de taux de réussite pour le moment
Latency p50: ——
Last verified: —Not verified yet

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

Uses platform quota
Synchronous response
Reads public data

Paramètres

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

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

Paramètres de requête
pageentierFacultatif
Exemple : 1
metricstableauFacultatif
JSON array; defaults to a thin set, so always name them
Exemple : ["spend","impressions","clicks","ctr","cpc","conversion","cost_per_conversion"]
end_datechaîneFacultatif
YYYY-MM-DD; the window is capped (about 30 days for most report types)
Exemple : 2026-07-28
filteringtableauFacultatif
JSON array of filter objects, e.g. [{"field_name":"campaign_ids","filter_type":"IN","filter_value":"[\"123\"]"}]
page_sizeentierFacultatif
max 1000, default 200
Exemple : 100
data_levelchaîneObligatoire
AUCTION_ADVERTISER | AUCTION_CAMPAIGN | AUCTION_ADGROUP | AUCTION_AD — must match the id dimension you ask for
Exemple : AUCTION_CAMPAIGN
dimensionstableauObligatoire
JSON array in the query string. One id dimension plus optionally stat_time_day for a daily series: ["campaign_id","stat_time_day"]
Exemple : ["campaign_id","stat_time_day"]
order_typechaîneFacultatif
ASC | DESC
Exemple : DESC
start_datechaîneFacultatif
YYYY-MM-DD, in the advertiser's timezone; required unless query_lifetime is true
Exemple : 2026-06-28
order_fieldchaîneFacultatif
Exemple : spend
report_typechaîneObligatoire
BASIC (performance) | AUDIENCE (demographic breakdowns) | PLAYABLE_MATERIAL | CATALOG | BC
Exemple : BASIC
advertiser_idchaîneObligatoire
Exemple : 7000000000000000000
query_lifetimebooléenFacultatif
true returns all-time totals and forbids start_date/end_date
Exemple : false

Exemples de code

Remplacez $TOOLSWITCH_KEY par la clé créée dans la 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());

Cette API de passerelle est en préversion ; son URL et son authentification peuvent changer. Les paramètres de l’exemple sont des données fictives. Les appels sont facturés à free, frais de service inclus.