DevelopersAPIReference and markets

API reference

Reference and markets

The 17 markets, and the lists other routes take values from: filters, category ids, channels, languages and LIVE gift prices.

8 routes
1 credit per call
Base URL https://api.tokconnect.com/v1

Shop Analytics markets

Lists the TikTok Shop markets Shop Analytics covers, with each market's currency, language and tier. core = markets the data source lists; extended = Poland, Italy, the Netherlands and Ireland, which it answers with local data but does not list. Pass the code as region to any Shop Analytics tool; other countries are refused. Default market is US. Example: {}.

GET/v1/markets

The supported markets

1 credit per call

Parameters

detailstring
compact (default) returns the useful fields; full adds the raw upstream payload (large).
Defaultcompact One ofcompactfull

Use it in Claude or ChatGPT

Connect https://mcp.tokconnect.com/mcp and your AI calls this as the shop_regions tool. Same data, same credit. MCP setup

MCP tool call

{
  "tool": "shop_regions",
  "arguments": {}
}

Request

curl "https://api.tokconnect.com/v1/markets" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"

import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/markets",
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])

const res = await fetch("https://api.tokconnect.com/v1/markets", {
  headers: { "X-API-Key": process.env.TOKCONNECT_API_KEY },
});
if (!res.ok) throw new Error((await res.json()).error?.message);
const { data, next_cursor } = await res.json();

Response

Example response

{
  "data": {
    "count": 17,
    "default": "US",
    "markets": [
      {
        "code": "US",
        "currency": "USD",
        "language": "en",
        "name": "United States",
        "tier": "core"
      },
      {
        "code": "GB",
        "currency": "GBP",
        "language": "en",
        "name": "United Kingdom",
        "tier": "core"
      },
      {
        "code": "DE",
        "currency": "EUR",
        "language": "de",
        "name": "Germany",
        "tier": "core"
      }
    ],
    "notes": [
      "Pass a market's code as region to product_top_selling, shop_top_selling, creator_top_selling, video_top_selling, live_top_selling, category_trends, product, shop, creator_commerce, video or live (their Shop Analytics methods).",
      "Amounts are in the market's currency; product, shop and creator names are in the market's language. Product and shop ids belong to one market: use them with the same region.",
      "Only these markets are accepted. The data source answers any other country code with one default dataset instead of local data, so TokConnect refuses them."
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}

Response fields

dataobjectThe tool's result. Compact by default; pass detail=full for the complete record.
data.countinteger
data.defaultstring
data.marketsarray
data.markets[].codestring
data.markets[].currencystring
data.markets[].languagestring
data.markets[].namestring
data.markets[].tierstring
data.notesarray
metaobject
meta.credits_chargedinteger1 on success.
meta.credits_remainingintegerCredits left this period, when known.
meta.request_idstringQuote it to support.
next_cursorstringPresent when there is another page: pass it back as cursor.

Errors

400
401
402
403
404
429
502
503

Try it Live call, 1 credit

Reference lists

Static lists other tools need: Creator Search Insights channels and languages, Explore category ids, LIVE gift coin prices, Ad Library regions, Creative Partner markets, and the Shop Analytics filters and sort fields. Example: {"method":"sales_filters"}.

GET/v1/reference/ad-regions

EU/UK regions the Ad Library covers

1 credit per call

Parameters

detailstring
compact (default) returns the useful fields; full adds the raw upstream payload (large).
Defaultcompact One ofcompactfull

Use it in Claude or ChatGPT

Connect https://mcp.tokconnect.com/mcp and your AI calls this as the reference tool with method: ad_regions. Same data, same credit. MCP setup

MCP tool call

{
  "tool": "reference",
  "arguments": {
    "method": "ad_regions"
  }
}

Request

curl "https://api.tokconnect.com/v1/reference/ad-regions" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"

import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/reference/ad-regions",
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])

const res = await fetch("https://api.tokconnect.com/v1/reference/ad-regions", {
  headers: { "X-API-Key": process.env.TOKCONNECT_API_KEY },
});
if (!res.ok) throw new Error((await res.json()).error?.message);
const { data, next_cursor } = await res.json();

Response

Example response

{
  "data": {
    "code": 0,
    "config_str": "FZWGxCEeVtiU4fNV9B3CI522OLi2P4B4TaUW+whWxOQ70wLG+tY0oT7fE6p0hZzG0gBjaSse9lpeOnImxViOSJA6YRzW5N2ZWPBkBC9PKOzGEj1J1zrz2V+iRuMKwXAiH5l7GX0jxlSK1nodWP+wvlkIpbC/wVZ+s5zqCeXyxBCC+UgmrIwivNHoXRhoMwYLrZMePDMSU3a/vKfnMHGwfJHi4yYCT9v4nQ==",
    "regions": [
      {
        "id": "AT",
        "name": "Austria"
      },
      {
        "id": "BE",
        "name": "Belgium"
      },
      {
        "id": "BG",
        "name": "Bulgaria"
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}

Response fields

dataobjectThe tool's result. Compact by default; pass detail=full for the complete record.
data.codeinteger
data.config_strstring
data.regionsarray
data.regions[].idstring
data.regions[].namestring
metaobject
meta.credits_chargedinteger1 on success.
meta.credits_remainingintegerCredits left this period, when known.
meta.request_idstringQuote it to support.
next_cursorstringPresent when there is another page: pass it back as cursor.

Errors

400
401
402
403
404
429
502
503

Try it Live call, 1 credit

GET/v1/reference/creative-markets

Creative Partner markets and dates

1 credit per call

Parameters

detailstring
compact (default) returns the useful fields; full adds the raw upstream payload (large).
Defaultcompact One ofcompactfull

Use it in Claude or ChatGPT

Connect https://mcp.tokconnect.com/mcp and your AI calls this as the reference tool with method: creative_markets. Same data, same credit. MCP setup

MCP tool call

{
  "tool": "reference",
  "arguments": {
    "method": "creative_markets"
  }
}

Request

curl "https://api.tokconnect.com/v1/reference/creative-markets" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"

import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/reference/creative-markets",
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])

const res = await fetch("https://api.tokconnect.com/v1/reference/creative-markets", {
  headers: { "X-API-Key": process.env.TOKCONNECT_API_KEY },
});
if (!res.ok) throw new Error((await res.json()).error?.message);
const { data, next_cursor } = await res.json();

Response

Example response

{
  "data": {
    "countries": [
      "CNOB",
      "TH",
      "ID"
    ],
    "end": "2026-10-05T00:00:00Z",
    "endUnix": 1791158400,
    "start": "2025-07-05T00:00:00Z",
    "startUnix": 1751673600
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}

Response fields

dataobjectThe tool's result. Compact by default; pass detail=full for the complete record.
data.countriesarray
data.endstring
data.endUnixinteger
data.startstring
data.startUnixinteger
metaobject
meta.credits_chargedinteger1 on success.
meta.credits_remainingintegerCredits left this period, when known.
meta.request_idstringQuote it to support.
next_cursorstringPresent when there is another page: pass it back as cursor.

Errors

400
401
402
403
404
429
502
503

Try it Live call, 1 credit

GET/v1/reference/csi-channels

demand_find_topics feeds and trending categories

1 credit per call

Parameters

detailstring
compact (default) returns the useful fields; full adds the raw upstream payload (large).
Defaultcompact One ofcompactfull

Use it in Claude or ChatGPT

Connect https://mcp.tokconnect.com/mcp and your AI calls this as the reference tool with method: csi_channels. Same data, same credit. MCP setup

MCP tool call

{
  "tool": "reference",
  "arguments": {
    "method": "csi_channels"
  }
}

Request

curl "https://api.tokconnect.com/v1/reference/csi-channels" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"

import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/reference/csi-channels",
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])

const res = await fetch("https://api.tokconnect.com/v1/reference/csi-channels", {
  headers: { "X-API-Key": process.env.TOKCONNECT_API_KEY },
});
if (!res.ok) throw new Error((await res.json()).error?.message);
const { data, next_cursor } = await res.json();

Response

Example response

{
  "data": {
    "channels": [
      {
        "categories": [
          "Fashion",
          "Food",
          "Gaming"
        ],
        "channel_key": "FOR_YOU",
        "languages": [
          "ar",
          "de",
          "en"
        ],
        "name": "Suggeriti",
        "tabDetails": [
          {
            "endpoint": "comprehensive",
            "key": "ALL",
            "name": "Tutti",
            "queryKey": "all"
          },
          {
            "endpoint": "comprehensive",
            "key": "CONTENT_GAP",
            "name": "Diversità di contenuti",
            "queryKey": "content_gap"
          },
          {
            "endpoint": "comprehensive",
            "key": "SEARCHES_BY_FOLLOWERS",
            "name": "Ricerche dei follower",
            "queryKey": "follower_searched"
          }
        ],
        "tabs": [
          "ALL",
          "CONTENT_GAP",
          "SEARCHES_BY_FOLLOWERS"
        ]
      },
      {
        "channel_key": "TRENDING",
        "name": "Di tendenza",
        "tabDetails": [
          {
            "endpoint": "trending",
            "key": "ALL",
            "name": "Tutti",
            "queryKey": "all"
          },
          {
            "endpoint": "trending",
            "key": "FASHION",
            "name": "Moda",
            "queryKey": "Fashion"
          },
          {
            "endpoint": "trending",
            "key": "FOOD",
            "name": "Cibo",
            "queryKey": "Food"
          }
        ],
        "tabs": [
          "ALL",
          "FASHION",
          "FOOD"
        ]
      }
    ],
    "trendingCategories": [
      "all",
      "Fashion",
      "Food"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}

Response fields

dataobjectThe tool's result. Compact by default; pass detail=full for the complete record.
data.channelsarray
data.channels[].categoriesarray
data.channels[].channel_keystring
data.channels[].languagesarray
data.channels[].namestring
data.channels[].tabDetailsarray
data.channels[].tabDetails[].endpointstring
data.channels[].tabDetails[].keystring
data.channels[].tabDetails[].namestring
data.channels[].tabDetails[].queryKeystring
data.channels[].tabsarray
data.trendingCategoriesarray
metaobject
meta.credits_chargedinteger1 on success.
meta.credits_remainingintegerCredits left this period, when known.
meta.request_idstringQuote it to support.
next_cursorstringPresent when there is another page: pass it back as cursor.

Errors

400
401
402
403
404
429
502
503

Try it Live call, 1 credit

GET/v1/reference/csi-languages

Language codes for demand_find_topics

1 credit per call

Parameters

detailstring
compact (default) returns the useful fields; full adds the raw upstream payload (large).
Defaultcompact One ofcompactfull

Use it in Claude or ChatGPT

Connect https://mcp.tokconnect.com/mcp and your AI calls this as the reference tool with method: csi_languages. Same data, same credit. MCP setup

MCP tool call

{
  "tool": "reference",
  "arguments": {
    "method": "csi_languages"
  }
}

Request

curl "https://api.tokconnect.com/v1/reference/csi-languages" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"

import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/reference/csi-languages",
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])

const res = await fetch("https://api.tokconnect.com/v1/reference/csi-languages", {
  headers: { "X-API-Key": process.env.TOKCONNECT_API_KEY },
});
if (!res.ok) throw new Error((await res.json()).error?.message);
const { data, next_cursor } = await res.json();

Response

Example response

{
  "data": {
    "languages": [
      {
        "id": "ar",
        "name": "العربية"
      },
      {
        "id": "de",
        "name": "Deutsch"
      },
      {
        "id": "en",
        "name": "English"
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}

Response fields

dataobjectThe tool's result. Compact by default; pass detail=full for the complete record.
data.languagesarray
data.languages[].idstring
data.languages[].namestring
metaobject
meta.credits_chargedinteger1 on success.
meta.credits_remainingintegerCredits left this period, when known.
meta.request_idstringQuote it to support.
next_cursorstringPresent when there is another page: pass it back as cursor.

Errors

400
401
402
403
404
429
502
503

Try it Live call, 1 credit

GET/v1/reference/explore-categories

Category ids for video_feed method=explore

1 credit per call

Parameters

detailstring
compact (default) returns the useful fields; full adds the raw upstream payload (large).
Defaultcompact One ofcompactfull

Use it in Claude or ChatGPT

Connect https://mcp.tokconnect.com/mcp and your AI calls this as the reference tool with method: explore_categories. Same data, same credit. MCP setup

MCP tool call

{
  "tool": "reference",
  "arguments": {
    "method": "explore_categories"
  }
}

Request

curl "https://api.tokconnect.com/v1/reference/explore-categories" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"

import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/reference/explore-categories",
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])

const res = await fetch("https://api.tokconnect.com/v1/reference/explore-categories", {
  headers: { "X-API-Key": process.env.TOKCONNECT_API_KEY },
});
if (!res.ok) throw new Error((await res.json()).error?.message);
const { data, next_cursor } = await res.json();

Response

Example response

{
  "data": {
    "categories": [
      {
        "id": 120,
        "name": "All"
      },
      {
        "id": 119,
        "name": "Singing & Dancing"
      },
      {
        "id": 104,
        "name": "Comedy"
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}

Response fields

dataobjectThe tool's result. Compact by default; pass detail=full for the complete record.
data.categoriesarray
data.categories[].idinteger
data.categories[].namestring
metaobject
meta.credits_chargedinteger1 on success.
meta.credits_remainingintegerCredits left this period, when known.
meta.request_idstringQuote it to support.
next_cursorstringPresent when there is another page: pass it back as cursor.

Errors

400
401
402
403
404
429
502
503

Try it Live call, 1 credit

GET/v1/reference/live-gifts

LIVE gifts and their coin prices

1 credit per call

Parameters

detailstring
compact (default) returns the useful fields; full adds the raw upstream payload (large).
Defaultcompact One ofcompactfull

Use it in Claude or ChatGPT

Connect https://mcp.tokconnect.com/mcp and your AI calls this as the reference tool with method: live_gifts. Same data, same credit. MCP setup

MCP tool call

{
  "tool": "reference",
  "arguments": {
    "method": "live_gifts"
  }
}

Request

curl "https://api.tokconnect.com/v1/reference/live-gifts" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"

import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/reference/live-gifts",
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])

const res = await fetch("https://api.tokconnect.com/v1/reference/live-gifts", {
  headers: { "X-API-Key": process.env.TOKCONNECT_API_KEY },
});
if (!res.ok) throw new Error((await res.json()).error?.message);
const { data, next_cursor } = await res.json();

Response

Example response

{
  "data": {
    "gifts": [
      {
        "coins": 1,
        "combo": true,
        "id": "1347121",
        "name": "Mirwas Beat"
      },
      {
        "coins": 1,
        "combo": true,
        "id": "1374221",
        "name": "Eye for an Eye"
      },
      {
        "coins": 1,
        "combo": true,
        "id": "1167779",
        "name": "Mantap"
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}

Response fields

dataobjectThe tool's result. Compact by default; pass detail=full for the complete record.
data.giftsarray
data.gifts[].coinsinteger
data.gifts[].comboboolean
data.gifts[].idstring
data.gifts[].namestring
metaobject
meta.credits_chargedinteger1 on success.
meta.credits_remainingintegerCredits left this period, when known.
meta.request_idstringQuote it to support.
next_cursorstringPresent when there is another page: pass it back as cursor.

Errors

400
401
402
403
404
429
502
503

Try it Live call, 1 credit

GET/v1/reference/sales-filters

Every Shop Analytics filter, its values and sort fields

1 credit per call

Parameters

detailstring
compact (default) returns the useful fields; full adds the raw upstream payload (large).
Defaultcompact One ofcompactfull

Use it in Claude or ChatGPT

Connect https://mcp.tokconnect.com/mcp and your AI calls this as the reference tool with method: sales_filters. Same data, same credit. MCP setup

MCP tool call

{
  "tool": "reference",
  "arguments": {
    "method": "sales_filters"
  }
}

Request

curl "https://api.tokconnect.com/v1/reference/sales-filters" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"

import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/reference/sales-filters",
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])

const res = await fetch("https://api.tokconnect.com/v1/reference/sales-filters", {
  headers: { "X-API-Key": process.env.TOKCONNECT_API_KEY },
});
if (!res.ok) throw new Error((await res.json()).error?.message);
const { data, next_cursor } = await res.json();

Response

Example response

{
  "data": {
    "category": "product_top_selling and creator_top_selling take category (name or id, levels 1-3, up to 5) with or without a keyword; find names with category_trends method=tree.",
    "market": "US by default; region picks any of US, GB, DE, FR, ES, JP, TH, VN, ID, MY, PH, BR, MX, PL, IT, NL, IE (call shop_regions for currency, language and tier)",
    "order": "order=desc (default) or asc on the ranking tools; asc lists the lowest first among matching rows.",
    "tools": {
      "category_trends": "method=list ranks categories by revenue; level keeps one category level.",
      "creator_top_selling": {
        "filters": [
          {
            "argument": "revenue",
            "meaning": "Revenue the creator drove in the market's currency over the window, e.g. >10000.",
            "values": "range: a-b, <a or >b"
          },
          {
            "argument": "followers",
            "meaning": "Followers, e.g. 50000-500000.",
            "values": "range: a-b, <a or >b"
          },
          {
            "argument": "engagement",
            "meaning": "Video engagement rate percent, e.g. >8.",
            "values": "range: a-b, <a or >b"
          }
        ],
        "sort": [
          "followers",
          "growth",
          "revenue"
        ]
      },
      "live_top_selling": "Top 10 by revenue for the window; no filters or sort.",
      "product_top_selling": {
        "filters": [
          {
            "argument": "revenue",
            "meaning": "Revenue in the market's currency over the window: a-b, <a or >b, e.g. 1000-10000.",
            "values": "range: a-b, <a or >b"
          },
          {
            "argument": "units",
            "meaning": "Units sold over the window, e.g. 500-5000 or >10000.",
            "values": "range: a-b, <a or >b"
          },
          {
            "argument": "revenue_growth",
            "meaning": "Revenue growth vs the previous equal window, percent, e.g. >30.",
            "values": "range: a-b, <a or >b"
          }
        ],
        "sort": [
          "creators",
          "growth",
          "price"
        ]
      },
      "shop_top_selling": {
        "filters": [
          {
            "argument": "revenue",
            "meaning": "Shop revenue in the market's currency over the window, e.g. >100000.",
            "values": "range: a-b, <a or >b"
          },
          {
            "argument": "revenue_growth",
            "meaning": "Revenue growth percent vs the previous window, e.g. >30.",
            "values": "range: a-b, <a or >b"
          },
          {
            "argument": "price",
            "meaning": "Average selling price in the market's currency, e.g. 20-100.",
            "values": "range: a-b, <a or >b"
          }
        ],
        "sort": [
          "growth",
          "revenue",
          "units"
        ]
      },
      "video_top_selling": "Top 10 by revenue for the window; no filters or sort."
    },
    "window": "7d, 30d, 90d, 180d, 365d, or start/end (YYYY-MM-DD). Data ends about 2 days before today."
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}

Response fields

dataobjectThe tool's result. Compact by default; pass detail=full for the complete record.
data.categorystring
data.marketstring
data.orderstring
data.toolsobject
data.tools.category_trendsstring
data.tools.creator_top_sellingobject
data.tools.creator_top_selling.filtersarray
data.tools.creator_top_selling.filters[].argumentstring
data.tools.creator_top_selling.filters[].meaningstring
data.tools.creator_top_selling.filters[].valuesstring
data.tools.creator_top_selling.sortarray
data.tools.live_top_sellingstring
data.tools.product_top_sellingobject
data.tools.product_top_selling.filtersarray
data.tools.product_top_selling.filters[].argumentstring
data.tools.product_top_selling.filters[].meaningstring
data.tools.product_top_selling.filters[].valuesstring
data.tools.product_top_selling.sortarray
data.tools.shop_top_sellingobject
data.tools.shop_top_selling.filtersarray
data.tools.shop_top_selling.filters[].argumentstring
data.tools.shop_top_selling.filters[].meaningstring
data.tools.shop_top_selling.filters[].valuesstring
data.tools.shop_top_selling.sortarray
data.tools.video_top_sellingstring
data.windowstring
metaobject
meta.credits_chargedinteger1 on success.
meta.credits_remainingintegerCredits left this period, when known.
meta.request_idstringQuote it to support.
next_cursorstringPresent when there is another page: pass it back as cursor.

Errors

400
401
402
403
404
429
502
503

Try it Live call, 1 credit