TikTok AdsTikTok AdsAdvertising

Your TikTok ads' spend, impressions, clicks, conversions

tiktok-ads.query

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

Price: freeAl precio del proveedor
Success rate: —Aún no hay datos de tasa de éxitoAún no hay datos de tasa de éxito
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	Obligatorio	Descripción	Ejemplo
Parámetros de consulta
`page`	entero	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`	cadena	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`	entero	Opcional	max 1000, default 200	`100`
`data_level`	cadena	Obligatorio	AUCTION_ADVERTISER \| AUCTION_CAMPAIGN \| AUCTION_ADGROUP \| AUCTION_AD — must match the id dimension you ask for	`AUCTION_CAMPAIGN`
`dimensions`	matriz	Obligatorio	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`	cadena	Opcional	ASC \| DESC	`DESC`
`start_date`	cadena	Opcional	YYYY-MM-DD, in the advertiser's timezone; required unless query_lifetime is true	`2026-06-28`
`order_field`	cadena	Opcional		`spend`
`report_type`	cadena	Obligatorio	BASIC (performance) \| AUDIENCE (demographic breakdowns) \| PLAYABLE_MATERIAL \| CATALOG \| BC	`BASIC`
`advertiser_id`	cadena	Obligatorio		`7000000000000000000`
`query_lifetime`	booleano	Opcional	true returns all-time totals and forbids start_date/end_date	`false`

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

Ejemplos de código

Sustituye $TOOLSWITCH_KEY por la clave que creaste en la consola.

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

La API de la pasarela está en versión preliminar; su URL y autenticación pueden cambiar. Los parámetros del ejemplo son datos de muestra. Las llamadas se facturan a free, incluida la tarifa de servicio.