API de TikTok Shop: filtros y parámetros de consulta

Para /api/v1/tiktok-shop/* with an API key (or the same path shapes under session /api/tiktok-shop/...). Route list: Referencia de la API.

Cómo se envían los parámetros

Mecanismo	Detalles
Cadena de consulta	Usual for GET
ENVIAR JSON	Merged with query on explore/count (avoids 414)
Formulario POST	Also merged
Empty / `«sin definir»`	Stripped

Explore endpoints

Normal explore proxies the upstream TikTok Shop v2 payload and WinningHunter injects:

credits_remaining — TikTok Shop daily search quota (not programmatic API credits). On Standard this is null con credits_unlimited: true (never -1).
credits_unlimited — verdad when the TikTok Shop daily search pool is unlimited
winninghunter_product_url / tiktok_shop_product_url on product rows (and product-bearing video rows) — both are WinningHunter app deep links today (same host pattern)
winninghunter_shop_url / tiktok_shop_url on shop rows (and shop-bearing rows) — same WH deep-link pattern
Country codes are normalized to uppercase (nosotros → EE. UU.) on explore/count

meta often accompanies datos. éxito / pagination appear only when the upstream response includes them (or on favorites explore paths). Do not assume creator/video-specific winninghunter_*_url keys — those are not injected today.

OBTENER/api/v1/tiktok-shop/products/explore

List / search TikTok Shop products. Also accepts POST with the same params as JSON.

Send Clave X-API on every request.

Query parameters

paíscadena
Default: EE. UU.
períodocadena
e.g. 7d, 30d, 90d, or day count.
Default: 30
límiteentero
Default: 20
páginaentero
Default: 1
clasificarcadena
Default: ingresos
pedidocadena
Default: desc
nombrecadena
Keyword.
ingresos mínimosnumber
ingresos máximosnumber
después decadena
Keyset cursor for deep pagination.

Solicitud

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/products/explore?country=US&period=30&limit=20&page=1&sort=revenue&order=desc&name=string&min_revenue=0&max_revenue=0&after=string"

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/products/explore?country=US&period=30&limit=20&page=1&sort=revenue&order=desc&name=string&min_revenue=0&max_revenue=0&after=string`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/tiktok-shop/products/explore?country=US&period=30&limit=20&page=1&sort=revenue&order=desc&name=string&min_revenue=0&max_revenue=0&after=string",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Respuesta

{
    "data": [
        {
            "id": "1729448464509734958",
            "product_title": "Toplux Magnesium Complex 8 Essential Magnesium Supplement",
            "product_image": "https://media.winninghunter.com/tiktok-shop/products/1729448464509734958_0.webp",
            "unit_price": "$14.97",
            "revenue": "$2.57m",
            "revenue_lifetime": 29785853.91,
            "sold_count": "161803",
            "sold_count_lifetime": 1989703,
            "creator_num": 16,
            "ctr": "4.1%",
            "sales_growth_rate": "-8.5%",
            "launch_date": "2026-02-26",
            "winninghunter_product_url": "https://app.winninghunter.com/tiktok-shop/product/1729448464509734958?period=30",
            "tiktok_shop_product_url": "https://app.winninghunter.com/tiktok-shop/product/1729448464509734958?period=30"
        }
    ],
    "meta": {
        "total": 245019,
        "page": 1,
        "limit": 20,
        "period": "30d",
        "next_cursor": "eyJ2IjoyNTc0Mzk0LjkxLCJpZCI6IjY5OWZmZDg3NmEzOGVlMGQzZmVhZDZiYyJ9"
    },
    "credits_remaining": null,
    "credits_unlimited": true
}

{
    "success": false,
    "error": "Unauthorized"
}

{
    "success": false,
    "error": "No API credits remaining. Buy an add-on pack or wait until next monthly reset.",
    "credits": {
        "used": 20000,
        "limit": 20000,
        "remaining": 0,
        "addon_remaining": 0,
        "total_remaining": 0
    },
    "purchase": {
        "url": "https://…/checkout-api-credits?credits=…"
    }
}

Row objects include many more upstream fields (tendencia de ingresos, category ids, commission, …). credits_remaining is the TikTok Shop daily search quota — null + credits_unlimited: true means unlimited (Standard). Basic plans see a non-negative integer and credits_unlimited: false. This is no GET /api/v1/credits. meta.next_cursor is the keyset cursor for después de.

OBTENER/api/v1/tiktok-shop/shops/explore

List / search TikTok shops. Also accepts POST JSON.

Send Clave X-API on every request.

Query parameters

paíscadena
Default: EE. UU.
períodocadena
Default: 30
límiteentero
Default: 20
páginaentero
Default: 1
clasificarcadena
Default: ingresos
pedidocadena
Default: desc
nombrecadena

Solicitud

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/shops/explore?country=US&period=30&limit=20&page=1&sort=revenue&order=desc&name=string"

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/shops/explore?country=US&period=30&limit=20&page=1&sort=revenue&order=desc&name=string`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/tiktok-shop/shops/explore?country=US&period=30&limit=20&page=1&sort=revenue&order=desc&name=string",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Respuesta

{
    "data": [
        {
            "id": "7495514739648989419",
            "shop_id": "7495514739648989419",
            "shop_name": "medicube US Store",
            "handle": "medicubeusstore",
            "shop_image": "https://media.winninghunter.com/tiktok-shop/shops/7495514739648989419.png",
            "seller_type": "BRAND",
            "product_count": 128,
            "video_count": 2298,
            "creator_count": 1235,
            "revenue_30_days": 19625456.71,
            "sold_count_30_days": 703153,
            "winninghunter_shop_url": "https://app.winninghunter.com/tiktok-shop/shop/7495514739648989419?period=30",
            "tiktok_shop_url": "https://app.winninghunter.com/tiktok-shop/shop/7495514739648989419?period=30"
        }
    ],
    "meta": {
        "total": 15494,
        "page": 1,
        "limit": 20,
        "period": "30d",
        "next_cursor": "eyJ2IjoxOTYyNTQ1Ni43MDk5OTk5OTMsImlkIjoiNjk5YWZlZjk4ZGUxMjI2NjUxYmFmODhjIn0"
    },
    "credits_remaining": null,
    "credits_unlimited": true
}

{
    "success": false,
    "error": "Unauthorized"
}

{
    "success": false,
    "error": "No API credits remaining. Buy an add-on pack or wait until next monthly reset.",
    "credits": {
        "used": 20000,
        "limit": 20000,
        "remaining": 0,
        "addon_remaining": 0,
        "total_remaining": 0
    },
    "purchase": {
        "url": "https://…/checkout-api-credits?credits=…"
    }
}

OBTENER/api/v1/tiktok-shop/creators/explore

List / search TikTok creators. Also accepts POST JSON.

Send Clave X-API on every request.

Query parameters

paíscadena
Default: EE. UU.
períodocadena
Default: 30
límiteentero
Default: 20
páginaentero
Default: 1
clasificarcadena
Default: ingresos
pedidocadena
Default: desc
nombrecadena

Solicitud

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/creators/explore?country=US&period=30&limit=20&page=1&sort=revenue&order=desc&name=string"

const res = await fetch(`${ORIGIN}/api/v1/tiktok-shop/creators/explore?country=US&period=30&limit=20&page=1&sort=revenue&order=desc&name=string`, {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.WH_API_KEY,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    f"{ORIGIN}/api/v1/tiktok-shop/creators/explore?country=US&period=30&limit=20&page=1&sort=revenue&order=desc&name=string",
    headers={"X-API-Key": os.environ["WH_API_KEY"]},
)
data = res.json()

Respuesta

{
    "data": [
        {
            "creator_id": "6737412251941389318",
            "creator_name": "Hannah Bentley",
            "nickname": "Hannah Bentley",
            "unique_id": "hannahbentley",
            "video_count": 172,
            "revenue_30_days": 890752.76,
            "revenue_7_days": 198025.52
        }
    ],
    "meta": {
        "total": 50000,
        "page": 1,
        "limit": 20,
        "period": "30d",
        "next_cursor": "eyJ2Ijo4OTA3NTIuNzYxODQ5NjI2MiwiaWQiOiI2OTlhZmVmODhkZTEyMjY2NTFiYWYzZmQifQ"
    },
    "credits_remaining": null,
    "credits_unlimited": true
}

{
    "success": false,
    "error": "Unauthorized"
}

{
    "success": false,
    "error": "No API credits remaining. Buy an add-on pack or wait until next monthly reset.",
    "credits": {
        "used": 20000,
        "limit": 20000,
        "remaining": 0,
        "addon_remaining": 0,
        "total_remaining": 0
    },
    "purchase": {
        "url": "https://…/checkout-api-credits?credits=…"
    }
}

Also: categorías/explorar, vídeos/explorar, and matching */count routes. Explore rows are upstream passthrough plus the WinningHunter URL injections listed above — many more keys appear on live rows than the samples. Handler soft-errors often look like { "error": "code", "message": "…" } (no éxito). Count routes do no always include credits_remaining.

credits_remaining in explore 200 bodies is the TikTok Shop daily search quota (same family as GET /api/v1/tiktok-shop/credits). Unlimited accounts return credits_remaining: null y credits_unlimited: true (the DB sentinel -1 is never returned). It is no the programmatic monthly pool from GET /api/v1/credits. Every call still costs 1 programmatic credit via the proxy.

Shared explore params

Parámetro	Por defecto	Notas
`página`	`1`	Integer page
`límite`	`20`	Page size
`después de`	—	Keyset cursor
`clasificar` / `pedido`	entity default / `desc`	Align with dashboard UI
`país`	`EE. UU.`
`período`	~30 days	`7d` / `30d` / `90d` or numeric days
`ID de categorías`, `id_de_categoría_l1`, …	—	When hierarchy applies

Entity filters (canonical names)

Productos — nombre, período, ID de categorías, ingresos mínimos / ingresos máximos, growth rates, número mínimo de artículos vendidos / máximo de artículos vendidos, price / commission / score / review / creator / launch filters. Alias: mín. vendido → número mínimo de artículos vendidos.

Tiendas — nombre, período, revenue / growth, rating, seller type, product / creator / video counts, channel strategy %. Aliases: min_gmv_30d → ingresos mínimos, etc.

Creadores — nombre, período, revenue / growth, followers / views, verified, product / video counts.

Vídeos — nombre, período, revenue / engagement / ROAS / ad spend / publish / flags (es un anuncio, es_afiliado, …).

Categorías — nivel, nombre, período, revenue / shop / video ratios. Default sort: origen de los ingresos.

Other useful GETs

Ruta	Notas
`GET .../products`	`página`, `límite`, `clasificar`, `fecha_de_inicio` / `fecha_hasta`, …
`GET .../search`	`q` required
`GET .../trending`	`límite`, `plazo`, `categoría`
`GET .../suggestions`	`tipo` + `q` required
`GET .../credits`	`{ "success": true, "credits_remaining": null, "credits_unlimited": true }` on Standard (or a positive `credits_remaining` on Basic) — TikTok search credits, not programmatic
`GET .../shops/details`	`id` required

Detail POST bodies (detalles de la tienda, detalles del producto, …): capture from the dashboard Network tab, replay on /api/v1/tiktok-shop/... with your key. Aggregate /total y /history routes are upstream passthrough — do not assume flat invented field names like avg_price o conversion_rate.

MCP

Explore tools (buscar_productos_en_TikTok, buscar_en_TikTok_Shops, buscar_creadores_de_TikTok, …) use the same filter semantics. See Referencia de herramientas MCP.

API de TikTok Shop: filtros y parámetros de consulta

Cómo se envían los parámetros#

Explore endpoints#

Query parameters

Query parameters

Query parameters

Shared explore params#

Entity filters (canonical names)#

Other useful GETs#

MCP#

Cómo se envían los parámetros

Explore endpoints

Shared explore params

Entity filters (canonical names)

Other useful GETs

MCP