TikTok AdsTikTok AdsAdvertising

Your TikTok ads' spend, impressions, clicks, conversions

tiktok-ads.query

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

Price: freePelo preço do provedor
Success rate: —Ainda não há dados da taxa de sucessoAinda não há dados da taxa de sucesso
Latency p50: ——
Last verified: —Not verified yet

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

Uses platform quota
Synchronous response
Reads public data

Parâmetros

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

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

Parâmetros de consulta
pageinteiroOpcional
Exemplo: 1
metricsmatrizOpcional
JSON array; defaults to a thin set, so always name them
Exemplo: ["spend","impressions","clicks","ctr","cpc","conversion","cost_per_conversion"]
end_datestringOpcional
YYYY-MM-DD; the window is capped (about 30 days for most report types)
Exemplo: 2026-07-28
filteringmatrizOpcional
JSON array of filter objects, e.g. [{"field_name":"campaign_ids","filter_type":"IN","filter_value":"[\"123\"]"}]
page_sizeinteiroOpcional
max 1000, default 200
Exemplo: 100
data_levelstringObrigatório
AUCTION_ADVERTISER | AUCTION_CAMPAIGN | AUCTION_ADGROUP | AUCTION_AD — must match the id dimension you ask for
Exemplo: AUCTION_CAMPAIGN
dimensionsmatrizObrigatório
JSON array in the query string. One id dimension plus optionally stat_time_day for a daily series: ["campaign_id","stat_time_day"]
Exemplo: ["campaign_id","stat_time_day"]
order_typestringOpcional
ASC | DESC
Exemplo: DESC
start_datestringOpcional
YYYY-MM-DD, in the advertiser's timezone; required unless query_lifetime is true
Exemplo: 2026-06-28
order_fieldstringOpcional
Exemplo: spend
report_typestringObrigatório
BASIC (performance) | AUDIENCE (demographic breakdowns) | PLAYABLE_MATERIAL | CATALOG | BC
Exemplo: BASIC
advertiser_idstringObrigatório
Exemplo: 7000000000000000000
query_lifetimebooleanoOpcional
true returns all-time totals and forbids start_date/end_date
Exemplo: false

Exemplos de código

Substitua $TOOLSWITCH_KEY pela chave criada no 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());

Esta API de gateway está em prévia; a URL e a autenticação podem mudar. Os parâmetros do exemplo são dados de amostra. As chamadas são cobradas a free, incluindo a taxa de serviço.