# TikTok data API

The TokConnect API gives your code TikTok data: TikTok Shop sales, products, shops and creators in 17 markets, plus videos, comments, search demand, sounds and hashtags. Every route runs the same tool as the TokConnect MCP server, so anything your AI can look up, your code can too.

The REST API is on every paid plan. [Paid plans](https://tokconnect.com/pricing/) from $34.99 a month. Free includes every research tool and 50 credits, but not the REST API.

[Get an API key](https://app.tokconnect.com/api-key)[Try this data free in the research agent](https://app.tokconnect.com/?q=Top-selling%20lip%20oil%20products%20on%20TikTok%20Shop%20US)

- **Base URL:** `https://api.tokconnect.com/v1`
- **Auth:** `X-API-Key` header
- **Cost:** 1 credit per call
- **Plans:** [Paid plans from $34.99 a month](https://tokconnect.com/pricing/)

## Your first request

Rank the best-selling TikTok Shop products for a keyword. Put your key in `TOKCONNECT_API_KEY` and run:

```bash
curl "https://api.tokconnect.com/v1/products/top?keyword=lip%20oil&region=US" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/products/top",
    params={
        "keyword": "lip oil",
        "region": "US",
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  region: "US",
});
const res = await fetch(`https://api.tokconnect.com/v1/products/top?${params}`, {
  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();
```

Every success comes back in the same envelope: the tool's JSON under `data`, `next_cursor` when there is another page, and `meta` with the credits charged.

200 OK:

```json
{
  "data": { "...": "the tool's JSON" },
  "next_cursor": "eyJwYWdlIjoyfQ",
  "meta": { "credits_charged": 1, "request_id": "req_…" }
}
```

New here? The [quickstart](https://tokconnect.com/docs/api/quickstart/) takes you from key to response in four steps. The full spec is at `GET /v1/openapi.json` (send your key).

## API reference

137 routes in 13 groups. Each one has parameters, code samples, the matching MCP tool and a console to try it.

- [**Rankings5 routes**The best-selling TikTok Shop products, shops and creators in any of 17 markets, ranked by revenue, units or growth, plus the top 10 videos and LIVEs.](https://tokconnect.com/docs/api/rankings/)
- [**Products18 routes**Everything about one TikTok Shop product: live price and stock, sales, daily trend, the creators and videos selling it, and what reviews say. Plus the store as shoppers see it now.](https://tokconnect.com/docs/api/products/)
- [**Shops10 routes**One TikTok Shop seller: its storefront, sales split by channel, daily trend, products, launches, affiliates and the videos that sell for it.](https://tokconnect.com/docs/api/shops/)
- [**Creators20 routes**A creator's public profile and posts, and their TikTok Shop business: what they sell, for which brands, and who follows them.](https://tokconnect.com/docs/api/creators/)
- [**Videos16 routes**One video or photo post: counts, comments, transcript, similar videos and the sales it drove. Plus samples of TikTok's own feeds and a fair comment giveaway draw.](https://tokconnect.com/docs/api/videos/)
- [**LIVE7 routes**One TikTok LIVE room: who is watching now, what it sold, and how the broadcast performed.](https://tokconnect.com/docs/api/live/)
- [**Search7 routes**Search TikTok the way the app answers right now: videos, photo posts, accounts, hashtags, LIVE rooms and places.](https://tokconnect.com/docs/api/search/)
- [**Demand and keywords16 routes**What people search for on TikTok, from TikTok's own Creator Search Insights, plus autocomplete and keyword ideas from TikTok and TikTok Shop.](https://tokconnect.com/docs/api/demand/)
- [**Categories5 routes**TikTok Shop categories ranked by revenue and growth, the category tree with ids, and a category's top products.](https://tokconnect.com/docs/api/categories/)
- [**Ads and Creative Center8 routes**TikTok's ads library and Creative Center: search ads by keyword, see where each ad ran and, when TikTok provides it, how viewers held on second by second, plus trending videos by market, SEO inspiration lists and Creative Partner agencies.](https://tokconnect.com/docs/api/creative-center/)
- [**Charts5 routes**TikTok's own leaderboards: the music charts, trending hashtags and searches, LIVE leaders and the top videos by market.](https://tokconnect.com/docs/api/charts/)
- [**Sounds, hashtags and places12 routes**Sounds, hashtags and tagged places, each with the videos that use it. Music marketers check a sound before they post; restaurants check the videos tagged at their address.](https://tokconnect.com/docs/api/sounds-hashtags-places/)
- [**Reference and markets8 routes**The 17 markets, and the lists other routes take values from: filters, category ids, channels, languages and LIVE gift prices.](https://tokconnect.com/docs/api/reference-lists/)

## Guides

- [**Quickstart**Key to first response in four steps, in curl, Python or JavaScript.](https://tokconnect.com/docs/api/quickstart/)
- [**Authentication**Send your key in one header. Where to find it and how to keep it safe.](https://tokconnect.com/docs/api/authentication/)
- [**Markets**The 17 TikTok Shop markets, their currencies, and the region parameter.](https://tokconnect.com/docs/api/markets/)
- [**Credits and limits**1 credit per call, failed calls never charged, and the per-plan rate limits.](https://tokconnect.com/docs/api/credits-and-limits/)
- [**Pagination**Walk long lists with next_cursor and cursor.](https://tokconnect.com/docs/api/pagination/)
- [**Errors**Every error code, what causes it and what to do.](https://tokconnect.com/docs/api/errors/)
- [**MCP**The same tools inside ChatGPT, Claude and Cursor.](https://tokconnect.com/docs/api/mcp/)
- [**CLI and Python**Every route as a terminal command or a Python method: npx tokconnect, pip install tokconnect.](https://tokconnect.com/docs/api/cli/)
- [**Changelog**Dated list of what changed in the API.](https://tokconnect.com/docs/api/changelog/)

Source: https://tokconnect.com/docs/api/

---

# TikTok Shop API quickstart

Make your first TikTok Shop API call in four steps. It needs a paid plan, from $34.99 a month billed yearly (Starter includes 600 credits a month); the same data is free to try in the research agent.

See the [plans](https://tokconnect.com/pricing/), or try the same question free in the [research agent](https://app.tokconnect.com/?q=Rank%20TikTok%20Shop%20US%20products%20matching%20lip%20oil%20by%20revenue).

## Make your first call

1. ### Get your key

   Open your API key page and copy the key. The same key works for the REST API and the MCP server. The 50 free credits work in the research agent and your AI app; the REST API needs a paid plan.

   [Get an API key](https://app.tokconnect.com/api-key) Not on a paid plan yet? [Compare plans](https://tokconnect.com/pricing/).

2. ### Keep it in an environment variable

   Shell:

   ```
   export TOKCONNECT_API_KEY="paste-your-key-here"
   ```

   Your code reads it from there, so the key never sits in a file you might commit.

3. ### Make the call

   This ranks TikTok Shop US products that match "lip oil" by revenue.

   ```bash
   curl "https://api.tokconnect.com/v1/products/top?keyword=lip%20oil&region=US" \
     -H "X-API-Key: $TOKCONNECT_API_KEY"
   ```

   ```python
   import os
   import requests
   
   r = requests.get(
       "https://api.tokconnect.com/v1/products/top",
       params={
           "keyword": "lip oil",
           "region": "US",
       },
       headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
       timeout=100,
   )
   r.raise_for_status()
   body = r.json()
   print(body["data"])
   ```

   ```javascript
   const params = new URLSearchParams({
     keyword: "lip oil",
     region: "US",
   });
   const res = await fetch(`https://api.tokconnect.com/v1/products/top?${params}`, {
     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();
   ```

4. ### Read the response

   The rows are under `data`. If `next_cursor` is there, pass it back as `cursor` for the next page. `meta.credits_charged` says what the call cost.

   200 OK, trimmed to two rows and four fields:

   ```json
   {
     "data": {
       "currency": "USD",
       "items": [
         {
           "product_title": "Hydrating Lip Gloss - High Shine & Tint…",
           "revenue": "$285.28k",
           "sale": 35660,
           "creator_num": 1473
         },
         {
           "product_title": "e.l.f. Glow Reviver Lip Oil Stick, Nour…",
           "revenue": "$177.48k",
           "sale": 17748,
           "creator_num": 688
         }
       ]
     },
     "next_cursor": "eyJwYWdlIjoyLCJzaXplIjozfQ",
     "meta": {
       "credits_charged": 1,
       "request_id": "req_3f9c2a1b7d4e"
     }
   }
   ```

5. ### Go further

   Change the market with `region` ([17 markets](https://tokconnect.com/docs/api/markets/)), browse the [rankings](https://tokconnect.com/docs/api/rankings/), or open any product, shop or creator by id. Or ask in plain words: [connect TokConnect to ChatGPT or Claude](https://app.tokconnect.com/mcp?app=chatgpt). Every route page has a **Try it** console, so you can test a call in the browser with your key before you write code.

Source: https://tokconnect.com/docs/api/quickstart/

---

# TikTok API authentication and keys

Send your API key in a header on every call. There is no other setup.

The REST API is on every paid plan. [Paid plans](https://tokconnect.com/pricing/) from $34.99 a month.

[Get an API key](https://app.tokconnect.com/api-key)

## Send your key

Use either header. They do the same thing.

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

```
curl "https://api.tokconnect.com/v1/markets" \
  -H "Authorization: Bearer $TOKCONNECT_API_KEY"
```

## Get your key

Sign in at [app.tokconnect.com/api-key](https://app.tokconnect.com/api-key) and copy your key. The REST API is part of every paid plan: Starter, Growth, Pro and Enterprise. A key on the Free plan returns 403 `plan_required`. One key covers the REST API and the MCP server, and both draw on the same credits.

## Keep it safe

- Call the API from your server, a script or a workflow tool. Never ship the key inside a web page or a mobile app.
- Read it from an environment variable or a secrets manager, not from source code. For local work, a `.env` file kept out of version control does the same job.
- The **Try it** consoles in these docs keep your key in this browser tab only and send it to `api.tokconnect.com` and nowhere else.

## When it fails

| Status | Code | Meaning |
|---|---|---|
| 401 | `unauthorized` | The key is missing or not valid. Check the header name and copy the key again. |
| 402 | `credits_exhausted` | Your credits have run out. See [credits and limits](https://tokconnect.com/docs/api/credits-and-limits/). |
| 403 | `plan_required` | The key is valid, but the REST API needs a paid plan. Free keys work in the research agent and MCP but not the REST API. [Choose a plan](https://tokconnect.com/pricing/) to switch the REST API on. |

401 Unauthorized:

```json
{
  "error": {
    "type": "unauthorized",
    "message": "No key, or the key is not valid.",
    "charged": false,
    "request_id": "req_0a1b2c3d4e5f",
    "docs": "https://tokconnect.com/docs/api/errors/"
  }
}
```

Every error code is on the [errors page](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/authentication/

---

# TikTok Shop markets in the API

TikTok Shop data covers 17 markets. Pass the country code as `region` and amounts come back in that market's currency. Leave it out and you get the US.

## The 17 markets

| region | Market | Currency | Tier |
|---|---|---|---|
| `US` | United States | `USD` | Core |
| `GB` | United Kingdom | `GBP` | Core |
| `DE` | Germany | `EUR` | Core |
| `FR` | France | `EUR` | Core |
| `ES` | Spain | `EUR` | Core |
| `JP` | Japan | `JPY` | Core |
| `TH` | Thailand | `THB` | Core |
| `VN` | Vietnam | `VND` | Core |
| `ID` | Indonesia | `IDR` | Core |
| `MY` | Malaysia | `MYR` | Core |
| `PH` | Philippines | `PHP` | Core |
| `BR` | Brazil | `BRL` | Core |
| `MX` | Mexico | `MXN` | Core |
| `PL` | Poland | `PLN` | Extended |
| `IT` | Italy | `EUR` | Extended |
| `NL` | Netherlands | `EUR` | Extended |
| `IE` | Ireland | `EUR` | Extended |

US, GB, DE, FR, ES, JP, TH, VN, ID, MY, PH, BR and MX are core markets. PL, IT, NL and IE are extended. Both tiers take the same `region` parameter. See live sales for any of these markets in the free [Shop Analytics tool](https://tokconnect.com/tools/tiktok-shop-analytics/).

## Using region

58 routes take `region`: the rankings, categories, and the sales, trend, creator and video data on one product, shop, creator, video or LIVE. Any other country code is refused with a 400.

Routes that read TikTok live, like search, a creator's posts or a product page, show what TikTok shows. On the storefront, search, keyword-page and category-page accept `region`; deals, flash sales and the other Shop pages read the US store.

```bash
curl "https://api.tokconnect.com/v1/products/top?keyword=lip%20oil&region=DE" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/products/top",
    params={
        "keyword": "lip oil",
        "region": "DE",
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  region: "DE",
});
const res = await fetch(`https://api.tokconnect.com/v1/products/top?${params}`, {
  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();
```

With `region=DE` the amounts in `data` come back in euros and `data.currency` says `EUR`.

Pick a market and pull its rankings.

[Get an API key](https://app.tokconnect.com/api-key)[Ask about a market](https://app.tokconnect.com/?q=Which%20TikTok%20Shop%20categories%20sell%20most%20in%20Germany%20this%20month%3F)

`GET /v1/markets` returns this list with each market's currency and language, so your code can read it instead of hard-coding it. The call costs 1 credit, so cache the result.

Source: https://tokconnect.com/docs/api/markets/

---

# TikTok API credits and rate limits

Every call costs 1 credit. Your plan sets how fast you can go.

The REST API is on every paid plan. [Paid plans](https://tokconnect.com/pricing/) from $34.99 a month.

[Get an API key](https://app.tokconnect.com/api-key)

## Credits

- **1 credit per call**, on every route.
- **Failed calls and refusals are never charged.**
- The REST API, the MCP server and the research agent share one balance.
- `meta.credits_charged` in each response says what the call cost.
- The Free plan has 50 credits (once) and every research tool, but not the REST API; the API starts on Starter.
- A plain-words question in the research agent usually uses about 3 lookups, so about 3 credits.

## Plans and rate limits

| Plan | Price | Credits a month | Requests a minute | At once |
|---|---|---|---|---|
| Free | $0, no card | 50 (once) | 60 | 2 |
| Starter | $49 a month ($34.99 billed yearly) | 600 | 120 | 4 |
| Growth | $99 a month ($69.99 billed yearly) | 2,500 | 200 | 6 |
| Pro | $199 a month ($139.99 billed yearly) | 10,000 | 300 | 8 |
| Enterprise | [Talk to us](mailto:dj@tokconnect.com?subject=TokConnect%20Enterprise) | Custom | 600 | 16 |

[Choose Starter](https://app.tokconnect.com/pricing?plan=starter&interval=month)[Choose Growth](https://app.tokconnect.com/pricing?plan=growth&interval=month)[Choose Pro](https://app.tokconnect.com/pricing?plan=pro&interval=month)

## Over the limit

Past either limit the API answers `429` and does not charge the call. The `Retry-After` header says how many seconds to wait. See [Errors](https://tokconnect.com/docs/api/errors/) for every code.

| Code | Cause | What to do |
|---|---|---|
| `rate_limited` | Too many requests this minute. | Wait `Retry-After` seconds, then carry on. |
| `too_concurrent` | Too many requests running at once. | Let one finish, or lower your worker count to your plan's limit. |

Python: respect Retry-After:

```
import time, requests

def call(url, **kw):
    for attempt in range(5):
        r = requests.get(url, **kw)
        if r.status_code != 429:
            return r
        time.sleep(min(int(r.headers.get("Retry-After", "5")), 60))
    raise RuntimeError("still rate limited after 5 tries")
```

Need more? Plans and credits are on the [pricing page](https://tokconnect.com/pricing/).

Source: https://tokconnect.com/docs/api/credits-and-limits/

---

# Paginate TikTok API results

Long lists come a page at a time. When a response has `next_cursor`, pass it back as `cursor` to get the next page.

## How it works

1. Make the call as usual.
2. If the response has `next_cursor`, call again with the same parameters plus `cursor=<next_cursor>`.
3. Stop when `next_cursor` is missing.

Treat the cursor as an opaque string and pass it back unchanged. The same cursor also appears as `data.next`; use whichever your client reads first. Each page is a call and costs 1 credit. Routes that page are marked **Paged** in the reference.

Set `limit` to change the page size (up to 100 on the [ranking routes](https://tokconnect.com/docs/api/rankings/)). At `limit=100`, 300 rows cost 3 credits. Rankings return up to about 700 rows per keyword (about 500 for shops).

```python
import os
import requests

url = "https://api.tokconnect.com/v1/products/top"
params = {"keyword": "lip oil", "region": "US"}
headers = {"X-API-Key": os.environ["TOKCONNECT_API_KEY"]}
rows = []

while True:
    r = requests.get(url, params=params, headers=headers, timeout=100)
    r.raise_for_status()
    body = r.json()
    rows += body["data"].get("items", [])
    if not body.get("next_cursor") or len(rows) >= 300:
        break
    params["cursor"] = body["next_cursor"]
```

```javascript
const rows = [];
let cursor;

do {
  const params = new URLSearchParams({ keyword: "lip oil", region: "US" });
  if (cursor) params.set("cursor", cursor);
  const res = await fetch(`https://api.tokconnect.com/v1/products/top?${params}`, {
    headers: { "X-API-Key": process.env.TOKCONNECT_API_KEY },
  });
  const body = await res.json();
  rows.push(...(body.data.items ?? []));
  cursor = body.next_cursor;
} while (cursor && rows.length < 300);
```

Needs a paid plan key. Try the same list free in the [research agent](https://app.tokconnect.com/?q=List%20the%20top%2020%20TikTok%20Shop%20US%20products%20for%20lip%20oil%20by%20revenue).

## Stop conditions

Stop when `next_cursor` is missing, or when you have the rows you need. Cap your loop at a row count, as both samples do, so a long list cannot run up credits.

Page through a ranking with your own key.

[Get an API key](https://app.tokconnect.com/api-key)[See the ranking routes that page](https://tokconnect.com/docs/api/rankings/)

Source: https://tokconnect.com/docs/api/pagination/

---

# TikTok API errors and status codes

Errors use plain HTTP status codes and a short machine-readable code. A call that fails is never charged.

## What an error looks like

400 Bad Request:

```json
{
  "error": {
    "type": "invalid_request",
    "message": "region must be one of the 17 supported markets",
    "charged": false,
    "request_id": "req_0a1b2c3d4e5f",
    "docs": "https://tokconnect.com/docs/api/errors/"
  }
}
```

Branch on `error.type`. The `message` is written for people and can change. `charged` is always `false`, and `docs` links here. Quote `request_id` when you contact support.

## Every code

| Status and code | Cause | Fix |
|---|---|---|
| 400 `invalid_request` | An argument is missing or not valid, or the market is not one of the 17. | Fix the argument the message names. |
| 401 `unauthorized` | No key, or the key is not valid. | Send your key in `X-API-Key` or `Authorization: Bearer`. See [authentication](https://tokconnect.com/docs/api/authentication/). |
| 402 `credits_exhausted` | No credits left this period. | Paid plans renew each month. The Free plan's 50 credits are one-off, so [choose a plan](https://tokconnect.com/pricing/) to continue. |
| 403 `plan_required` | The REST API needs a paid plan, from $34.99 a month. | [See plans](https://tokconnect.com/pricing/). |
| 403 `forbidden` | A browser request from a site that may not call the API. | Call the API from your server, not from a web page. |
| 404 `not_found` | The route does not exist, or no record matches the id. | Check the path against this reference. |
| 429 `rate_limited` | Too many requests this minute. | Wait the `Retry-After` seconds. See [limits](https://tokconnect.com/docs/api/credits-and-limits/). |
| 429 `too_concurrent` | Too many requests at once. | Wait the `Retry-After` seconds, or run fewer calls in parallel. |
| 502 `upstream_failed` | TikTok returned nothing for this input. | Retry, or check the id. The call is never charged. |
| 503 `server_busy` | The API is busy for a moment. | Retry in a few seconds. |

## Retrying

Retry `429`, `502` and `503`. For `429`, wait the `Retry-After` seconds first. Do not retry `400`, `401`, `402` or `403` without changing something.

### 402 and 429 bodies

402 Payment Required:

```json
{
  "error": {
    "type": "credits_exhausted",
    "message": "No credits left this period.",
    "charged": false,
    "request_id": "req_0a1b2c3d4e5f",
    "docs": "https://tokconnect.com/docs/api/errors/"
  }
}
```

429 Too Many Requests, with the header Retry-After: 30:

```json
{
  "error": {
    "type": "rate_limited",
    "message": "Too many requests this minute.",
    "charged": false,
    "retry_after": 30,
    "request_id": "req_0a1b2c3d4e5f",
    "docs": "https://tokconnect.com/docs/api/errors/"
  }
}
```

### 404, 502 and 503 bodies

404 Not Found:

```json
{
  "error": {
    "type": "not_found",
    "message": "No record matches this id.",
    "charged": false,
    "request_id": "req_0a1b2c3d4e5f",
    "docs": "https://tokconnect.com/docs/api/errors/"
  }
}
```

502 Bad Gateway:

```json
{
  "error": {
    "type": "upstream_failed",
    "message": "TikTok returned nothing for this input.",
    "charged": false,
    "request_id": "req_0a1b2c3d4e5f",
    "docs": "https://tokconnect.com/docs/api/errors/"
  }
}
```

503 Service Unavailable:

```json
{
  "error": {
    "type": "server_busy",
    "message": "The API is busy for a moment. Retry in a few seconds.",
    "charged": false,
    "request_id": "req_0a1b2c3d4e5f",
    "docs": "https://tokconnect.com/docs/api/errors/"
  }
}
```

Source: https://tokconnect.com/docs/api/errors/

---

# TikTok MCP server: use TokConnect in ChatGPT, Claude and Cursor

Every route in this reference is available on the TokConnect MCP server, grouped into 34 tools that take a `method` argument. Connect it once and ChatGPT, Claude or Cursor can pull the same TikTok data while you talk to it.

**Use MCP** when a person is asking the questions. **Use the REST API** when your code runs the same calls on a schedule, in a pipeline or inside your product.

The free plan includes 50 credits to try it in your AI.

[Connect your AI](https://app.tokconnect.com/mcp)[ChatGPT](https://app.tokconnect.com/mcp?app=chatgpt)[Claude](https://app.tokconnect.com/mcp?app=claude)[Cursor](https://app.tokconnect.com/mcp?app=cursor)[All AI setups](https://tokconnect.com/connect/)

- **Server:** `https://mcp.tokconnect.com/mcp`
- **Credits:** 1 per call, same balance as the API

## Connect your AI

Setup guides for each app:

- [ChatGPT](https://tokconnect.com/connect/chatgpt/) and [Claude](https://tokconnect.com/connect/claude-desktop/): add TokConnect as a connector and sign in. No key to copy.
- [Cursor](https://tokconnect.com/connect/cursor/), [Claude Code](https://tokconnect.com/connect/claude-code/), [Codex](https://tokconnect.com/connect/codex/), [VS Code](https://app.tokconnect.com/mcp?app=vscode) and [Gemini CLI](https://tokconnect.com/connect/gemini-cli/): add the server URL with your key as a Bearer header. Your key is on the [API key page](https://app.tokconnect.com/api-key).
- [n8n](https://tokconnect.com/connect/n8n/) and any other MCP client: use the same server URL and key.

Claude Code:

```
claude mcp add --transport http tokconnect https://mcp.tokconnect.com/mcp \
  --header "Authorization: Bearer $TOKCONNECT_API_KEY"
```

## Routes and tools

Each route page shows its MCP tool, the `method` it maps to and the arguments, in a box titled **Use it in Claude or ChatGPT**. For example, `GET /v1/products/{id}/trend` is the `product` tool with `method: trend`.

> Ask: "Top 10 TikTok Shop US products for lip oil this month, with revenue and creators."
>
> [Try it in the research agent](https://app.tokconnect.com/?q=Top%2010%20TikTok%20Shop%20US%20products%20for%20lip%20oil%20this%20month%2C%20with%20revenue%20and%20creators.)

## Tools and where each is documented

Each tool takes a `method` argument and maps to the routes on its page.

- [`ad_library`](https://tokconnect.com/docs/api/creative-center/#tool-ad-library)
- [`category_trends`](https://tokconnect.com/docs/api/categories/#tool-category-trends)
- [`charts`](https://tokconnect.com/docs/api/charts/#tool-charts)
- [`creative_center`](https://tokconnect.com/docs/api/creative-center/#tool-creative-center)
- [`creator`](https://tokconnect.com/docs/api/creators/#tool-creator)
- [`creator_commerce`](https://tokconnect.com/docs/api/creators/#tool-creator-commerce)
- [`creator_playlist`](https://tokconnect.com/docs/api/creators/#tool-creator-playlist)
- [`creator_search`](https://tokconnect.com/docs/api/search/#tool-creator-search)
- [`creator_top_selling`](https://tokconnect.com/docs/api/rankings/#tool-creator-top-selling)
- [`demand_find_topics`](https://tokconnect.com/docs/api/demand/#tool-demand-find-topics)
- [`demand_keywords`](https://tokconnect.com/docs/api/demand/#tool-demand-keywords)
- [`demand_topic`](https://tokconnect.com/docs/api/demand/#tool-demand-topic)
- [`hashtag`](https://tokconnect.com/docs/api/sounds-hashtags-places/#tool-hashtag)
- [`hashtag_search`](https://tokconnect.com/docs/api/search/#tool-hashtag-search)
- [`live`](https://tokconnect.com/docs/api/live/#tool-live)
- [`live_search`](https://tokconnect.com/docs/api/search/#tool-live-search)
- [`live_top_selling`](https://tokconnect.com/docs/api/rankings/#tool-live-top-selling)
- [`pick_comment_winners`](https://tokconnect.com/docs/api/videos/#tool-pick-comment-winners)
- [`place`](https://tokconnect.com/docs/api/sounds-hashtags-places/#tool-place)
- [`place_search`](https://tokconnect.com/docs/api/search/#tool-place-search)
- [`product`](https://tokconnect.com/docs/api/products/#tool-product)
- [`product_top_selling`](https://tokconnect.com/docs/api/rankings/#tool-product-top-selling)
- [`reference`](https://tokconnect.com/docs/api/reference-lists/#tool-reference)
- [`shop`](https://tokconnect.com/docs/api/shops/#tool-shop)
- [`shop_browse`](https://tokconnect.com/docs/api/products/#tool-shop-browse)
- [`shop_regions`](https://tokconnect.com/docs/api/reference-lists/#tool-shop-regions)
- [`shop_top_selling`](https://tokconnect.com/docs/api/rankings/#tool-shop-top-selling)
- [`sound`](https://tokconnect.com/docs/api/sounds-hashtags-places/#tool-sound)
- [`sound_search`](https://tokconnect.com/docs/api/sounds-hashtags-places/#tool-sound-search)
- [`video`](https://tokconnect.com/docs/api/videos/#tool-video)
- [`video_feed`](https://tokconnect.com/docs/api/videos/#tool-video-feed)
- [`video_search`](https://tokconnect.com/docs/api/search/#tool-video-search)
- [`video_top_selling`](https://tokconnect.com/docs/api/rankings/#tool-video-top-selling)

The REST API is on every paid plan. [Paid plans](https://tokconnect.com/pricing/) from $34.99 a month.

[Get an API key](https://app.tokconnect.com/api-key)

Source: https://tokconnect.com/docs/api/mcp/

---

# TokConnect CLI and Python client

The TokConnect CLI turns every route in this reference into a command: `tokconnect products top --keyword "lip oil"`. It prints the API's JSON, so it works in scripts, in `jq` pipelines and in an AI agent's shell. The Python package adds a client with one method per route.

The REST API is on every paid plan. [Paid plans](https://tokconnect.com/pricing/) from $34.99 a month.

[Get an API key](https://app.tokconnect.com/api-key)[npm](https://www.npmjs.com/package/tokconnect)[PyPI](https://pypi.org/project/tokconnect/)

- **npm:** `npx tokconnect` (Node.js 18+)
- **PyPI:** `pip install tokconnect` (Python 3.9+)

## Install and sign in

Use either package. Both have the same commands and no other dependencies.

Install:

```
npx tokconnect login
# or
pip install tokconnect && tokconnect login
```

`tokconnect login` saves your key to `~/.config/tokconnect/config.json`, readable only by you. You can also set `TOKCONNECT_API_KEY` or pass `--key`. Your key is on the [API key page](https://app.tokconnect.com/api-key).

## Commands

Each route `/v1/<group>/<words>` is the command `tokconnect <group> <words>`. Ids and TikTok links in the path become arguments, and query parameters become options with the same names.

Examples:

```
tokconnect products top --keyword "lip oil" --region US --limit 5
tokconnect videos transcript https://www.tiktok.com/@creator/video/7691522530129022221
tokconnect searches list --keyword "glass skin"
tokconnect products top --keyword "phone case" --all --max-pages 5
```

- `tokconnect commands` lists every command (`--json` for agents).
- `tokconnect describe products top` shows the options, credits and an example.
- `tokconnect call GET /v1/...` reaches any route by path, and `tokconnect sync` picks up new routes without updating the CLI.
- `--all` follows `next_cursor` and merges the pages; each page costs credits.

## Output and exit codes

The output is the API response: `data`, `next_cursor` and `meta`. It is pretty-printed in a terminal and compact when piped. Errors go to stderr with the API's error JSON. On 429 and 503 the CLI waits the `Retry-After` seconds and retries twice; see [Errors](https://tokconnect.com/docs/api/errors/).

Exit codes: `0` ok, `1` API or network error, `2` bad usage or request, `3` key missing or not allowed, `4` out of credits, `5` rate limited.

## Python client

Python:

```
from tokconnect import Client, TokConnectError

tc = Client()  # TOKCONNECT_API_KEY, the saved key, or Client(api_key="...")
best = tc.products.top(keyword="lip oil", region="US", limit=5)
for p in best["data"]["items"]:
    print(p["product_title"], p["revenue"])

tc.creators.shop_sales("tokconnect", start="2026-10-01")
tc.run("searches list", keyword="glass skin")
```

Each method returns the response JSON. Errors raise `TokConnectError` with `status`, `type` and `body`.

The REST API is on every paid plan. [Paid plans](https://tokconnect.com/pricing/) from $34.99 a month.

[Get an API key](https://app.tokconnect.com/api-key)[Quickstart](https://tokconnect.com/docs/api/quickstart/)[MCP](https://tokconnect.com/docs/api/mcp/)

Source: https://tokconnect.com/docs/api/cli/

---

# API changelog

What changed in the API, newest first. Each entry says whether it was added, changed or fixed.

## 10 November 2026

- **Added.** The TokConnect CLI on npm (npx tokconnect) and PyPI (pip install tokconnect), with a Python client: every route as a command or method. See CLI and Python.

## 2 November 2026

- **Added.** The REST API is on every paid plan: Starter, Growth, Pro and Enterprise. A key on the Free plan returns 403 plan_required.
- **Added.** This reference: 137 routes in 13 groups, each with parameters, code samples in curl, Python and JavaScript, its MCP tool and a Try it console.

## 31 October 2026

- **Changed.** MCP server release 4. Every REST route runs the same tool as the MCP server, so the routes return what the tools return.

## 30 October 2026

- **Fixed.** Parameter definitions in /v1/openapi.json that made some routes return 502. Failed calls were refunded.

Current reference: 137 routes in 13 groups.

[Get an API key](https://app.tokconnect.com/api-key)[Errors](https://tokconnect.com/docs/api/errors/)[Credits and limits](https://tokconnect.com/docs/api/credits-and-limits/)

Source: https://tokconnect.com/docs/api/changelog/

---

# TikTok Shop rankings API

The best-selling TikTok Shop products, shops and creators in any of 17 markets, ranked by revenue, units or growth, plus the top 10 videos and LIVEs.

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

Call these routes with your own key, or ask the same question in plain words.

[See today's best sellers](https://tokconnect.com/trends/products/best-sellers/)[Get an API key](https://app.tokconnect.com/api-key)[Ask it in plain words](https://app.tokconnect.com/?q=Top%2010%20TikTok%20Shop%20UK%20shops%20by%20revenue%20over%20the%20last%2030%20days%2C%20with%20growth%20against%20the%20month%20before.)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/products/top`](https://tokconnect.com/docs/api/rankings/#get-products-top) | Products ranked by sales |
| [GET `/v1/shops/top`](https://tokconnect.com/docs/api/rankings/#get-shops-top) | Shops ranked by sales |
| [GET `/v1/affiliates/top`](https://tokconnect.com/docs/api/rankings/#get-affiliates-top) | Creators ranked by sales |
| [GET `/v1/videos/top-selling`](https://tokconnect.com/docs/api/rankings/#get-videos-top-selling) | Top videos by sales |
| [GET `/v1/lives/top-selling`](https://tokconnect.com/docs/api/rankings/#get-lives-top-selling) | Top LIVEs by sales |

## Common parameters

These read the same on the routes below that take them.

- `region` (string): Market as an ISO country code, default US. Amounts are in the market's currency. See [Markets](https://tokconnect.com/docs/api/markets/).
- `window` (string): Date range ending at the last complete day (about 2 days ago). Default 30d. Use start and end for a custom range. **One of** `7d` `30d` `90d` `180d` `365d`.
- `start` (string): Custom range start, YYYY-MM-DD.
- `end` (string): Custom range end, YYYY-MM-DD (capped at the last complete day).
- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## Top-selling TikTok Shop products

Shop Analytics

Products ranked by estimated sales over a date range: revenue, units, video, LIVE and showcase split, growth, price, commission, creators, launch date, daily trend. `keyword` matches words in product titles; `category` takes a category name or id (levels 1 to 3, several allowed; no keyword needed); both together narrow further.

With neither, the result is the top 10 products for the most recent days (about 6). Up to 100 rows per page with cursor paging, about 700 rows per keyword. For what a shopper sees right now, use [Products](https://tokconnect.com/docs/api/products/).

### [Products ranked by sales](https://tokconnect.com/docs/api/rankings/#get-products-top)

`GET /v1/products/top`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `keyword` (string): Words from product titles, e.g. 'vitamin c serum' or 'lip oil'. Ranks every matching product over your window. If keyword and category are both omitted, the result is the top 10 products for the most recent days (about 6), whatever window is set: pass a keyword or category to get more than 10 rows or a specific window.
- `limit` (integer): Results per page. Max 100 per page; pass next as cursor for the following page. Up to about 700 rows per keyword (`max_rows` scans up to 3,000 in the US). Without a keyword or category: 10 rows. Values above the maximum are lowered and reported in notes.

**17 more optional parameters**

- `affiliate` (string): Filter. PUBLIC_PLAN = open affiliate plan; NON_AFFILIATE = not open to affiliates. **One of** `PUBLIC_PLAN` `NON_AFFILIATE`.
- `category` (array of string): Narrow to one or more Shop categories (up to 5), by name or numeric id, levels 1 to 3: "Skincare", "Pet Supplies", "Beauty & Personal Care","Health" or "601450". Without a keyword the products of the category are found by merging several generic keyword searches (the Shop data needs a keyword), and the result says how many keyword sweeps and distinct rows that gave. Find names and ids with [`GET /v1/categories/tree`](https://tokconnect.com/docs/api/categories/#get-categories-tree).
- `commission` (string): Filter. Affiliate commission percent, e.g. 15-35.
- `creator_conversion` (string): Filter. Percent of creators who made a sale, e.g. >45.
- `creators` (string): Filter. Number of creators selling it, e.g. 10-50.
- `launched_within_days` (string): Filter. Only products launched in the last N days. **One of** `3` `7` `30` `180` `365`.
- `max_rows` (integer): Scan up to this many matching products (101-3000) before sorting, to go past the 700-row cap; the top limit rows are returned. Needs keyword; US market only; not with category.
- `order` (string): desc (default, highest first) or asc (lowest first among the matching rows; pair it with a revenue or units filter to skip dead listings). Applies with a keyword or category. **One of** `desc` `asc`.
- `price` (string): Filter. Average selling price in the market's currency, e.g. <20 or 20-100.
- `rating` (string): Filter. Product rating, e.g. >4.5.
- `revenue` (string): Filter. Revenue in the market's currency over the window: a-b, <a or >b, e.g. 1000-10000.
- `revenue_growth` (string): Filter. Revenue growth vs the previous equal window, percent, e.g. >30.
- `sales_channel` (string): Filter. Where the revenue came from: VIDEO, LIVE or SHOWCASE (shop tab and search). Several: comma separated, e.g. VIDEO,LIVE. Values: VIDEO, LIVE, SHOWCASE.
- `seller_type` (string): Filter. Who sold it: the seller's own accounts, independent affiliates, or the Shop mall. **One of** `BELONGED_TO_SELLER` `INDEPENDENT` `SHOPPING_MALL`.
- `shipping` (string): Filter. local = ships from warehouses in the market; global = cross-border. **One of** `local` `global`.
- `sort` (string): Ranking metric: creators, growth, price, revenue, units. Default revenue. growth favours brand-new items (shown as >999.9%); pair it with a revenue or units filter. Applies with a keyword or category. **One of** `creators` `growth` `price` `revenue` `units`.
- `units` (string): Filter. Units sold over the window, e.g. 500-5000 or >10000.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product_top_selling` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product_top_selling",
  "arguments": {
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/top?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/products/top",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/products/top?${params}`, {
  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:

```json
{
  "data": {
    "count": 3,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": true,
    "items": [
      {
        "commission_rate": "13%",
        "creator_conversion_ratio": 0.47589952477936187,
        "creator_num": 1473,
        "delivery_type": "local",
        "id": "1731896769144001226",
        "is_full_service": 0,
        "is_overseas": 0,
        "is_tokopedia": 0,
        "launch_date": "2025-10-18",
        "live_revenue": "$5.19k",
        "max_real_price": "$13.92",
        "min_real_price": "$13.92",
        "pri_cate_id": 601450,
        "product_rating": 4.4,
        "product_title": "Hydrating Lip Gloss - High Shine & Tinted, Infused with Hyaluronic Acid, Jojoba Oil & Shea Butter",
        "revenue": "$285.28k",
        "revenue_grouping_rate": "16.2%",
        "revenue_trend": [
          4760,
          0
        ],
        "sale": 35660,
        "sec_cate_id": 848648,
        "shipping_fee": "$0.00",
        "showcase_revenue": "$112.00",
        "ter_cate_id": 601534,
        "total": 407,
        "unit_price": "$8.00",
        "video_revenue": "$279.98k"
      },
      {
        "commission_rate": "15%",
        "creator_conversion_ratio": 0.47819767441860467,
        "creator_num": 688,
        "delivery_type": "local",
        "id": "1732111846411833635",
        "is_full_service": 0,
        "is_overseas": 0,
        "is_tokopedia": 0,
        "launch_date": "2025-12-02",
        "live_revenue": "$2.72k",
        "max_real_price": "$14.00",
        "min_real_price": "$14.00",
        "pri_cate_id": 601450,
        "product_rating": 4.6,
        "product_title": "e.l.f. Glow Reviver Lip Oil Stick, Nourishing Lip Oil Stick Infused with Squalane Shea Butter & Jojoba Oil for Buildable Color & Soft Shine 3.3mL",
        "revenue": "$177.48k",
        "revenue_grouping_rate": "25.6%",
        "revenue_trend": [
          2700,
          5480
        ],
        "sale": 17748,
        "sec_cate_id": 848648,
        "shipping_fee": "$0.00",
        "showcase_revenue": "$30.00",
        "ter_cate_id": 601534,
        "total": 407,
        "unit_price": "$10.00",
        "video_revenue": "$174.73k"
      }
    ],
    "keyword": "lip oil",
    "market": "US",
    "next": "eyJwYWdlIjoyLCJzaXplIjozfQ",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "see_also": "Pass a row's id to product: method=trend (daily), creators (who sells it), video_sales, page (live price and stock).",
    "sortedBy": "revenue",
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totalMatched": 407,
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyLCJzaXplIjozfQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.items`array
- `data.items[].commission_rate`string
- `data.items[].creator_conversion_ratio`number
- `data.items[].creator_num`integer
- `data.items[].delivery_type`string
- `data.items[].id`string
- `data.items[].is_full_service`integer
- `data.items[].is_overseas`integer
- `data.items[].is_tokopedia`integer
- `data.items[].launch_date`string
- `data.items[].live_revenue`string
- `data.items[].max_real_price`string
- `data.items[].min_real_price`string
- `data.items[].pri_cate_id`integer
- `data.items[].product_rating`number
- `data.items[].product_title`string
- `data.items[].revenue`string
- `data.items[].revenue_grouping_rate`string
- `data.items[].revenue_trend`array
- `data.items[].sale`integer
- `data.items[].sec_cate_id`integer
- `data.items[].shipping_fee`string
- `data.items[].showcase_revenue`string
- `data.items[].ter_cate_id`integer
- `data.items[].total`integer
- `data.items[].unit_price`string
- `data.items[].video_revenue`string
- `data.keyword`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.see_also`string
- `data.sortedBy`string
- `data.source`string
- `data.totalMatched`integer
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Top-selling TikTok Shop sellers

Shop Analytics

TikTok Shop sellers ranked by estimated sales over a date range: revenue, units, growth, average price, and revenue split across own accounts, affiliates and the mall. `keyword` is a shop or brand name, matched loosely, for example medicube; it is not a product type. Without a keyword you get the top 10 shops for the most recent days (about 6); `type=brands` lists the top 10 brands.

For the shops behind a product type, rank products with [`GET /v1/products/top`](https://tokconnect.com/docs/api/rankings/#get-products-top), then read the seller id from each product. There is no category scope for shops. Up to 100 rows per page with cursor paging, about 500 rows per keyword.

### [Shops ranked by sales](https://tokconnect.com/docs/api/rankings/#get-shops-top)

`GET /v1/shops/top`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `keyword` (string): A shop or brand NAME, matched loosely against shop names, e.g. 'medicube'. It does not match product types: 'skincare' finds shops with that word in their name. For the shops behind a product type or category, rank products with [`GET /v1/products/top`](https://tokconnect.com/docs/api/rankings/#get-products-top) (category or a product keyword), call [`GET /v1/products/{id}`](https://tokconnect.com/docs/api/products/#get-products-id) on the top items for their sellerId, then use shop or call this tool with the brand names found. If keyword is omitted, the result is the top 10 shops for the most recent days (about 6), whatever window is set: pass a shop or brand name when you want more than 10 rows or a specific window.
- `limit` (integer): Results per page. Max 100 per page; pass next as cursor for the following page. Up to about 500 rows per keyword. Without a keyword: 10 rows. Values above the maximum are lowered and reported in notes.

**8 more optional parameters**

- `order` (string): desc (default, highest first) or asc (lowest first among the matching rows; pair it with a revenue or units filter to skip dead listings). Applies with a keyword. **One of** `desc` `asc`.
- `price` (string): Filter. Average selling price in the market's currency, e.g. 20-100.
- `revenue` (string): Filter. Shop revenue in the market's currency over the window, e.g. >100000.
- `revenue_growth` (string): Filter. Revenue growth percent vs the previous window, e.g. >30.
- `revenue_source` (string): Filter. Main revenue source: own accounts, affiliates, or the mall. **One of** `SELF_ACCOUNTS` `AFFILIATE` `SHOPPING_MALL`.
- `seller_type` (string): Filter. BRAND or RETAILER. **One of** `BRAND` `RETAILER`.
- `sort` (string): Ranking metric: growth, revenue, units. Default revenue. growth favours brand-new items (shown as >999.9%); pair it with a revenue or units filter. Applies with a keyword. **One of** `growth` `revenue` `units`.
- `type` (string): shops (default) or brands (the top 10 brands for the most recent days; keyword, filters and sort do not apply). **One of** `shops` `brands`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop_top_selling` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop_top_selling",
  "arguments": {
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/top?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/shops/top",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/shops/top?${params}`, {
  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:

```json
{
  "data": {
    "count": 3,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": true,
    "items": [
      {
        "affiliate_revenue": "$192.14k",
        "id": "7495499730147969966",
        "is_full_service": 0,
        "live_revenue": "$38.81k",
        "main_category": {
          "pri_main_category": [
            "601450"
          ],
          "sec_main_category": [
            "601450-856208"
          ],
          "ter_main_category": [
            "601450-856208-856080"
          ]
        },
        "name": "Eternal Perfume Oils",
        "region": "US",
        "revenue": "$225.43k",
        "revenue_grouping_rate": "7.3%",
        "revenue_trend": [
          6719.6,
          6453.8
        ],
        "sale": 4036,
        "self_promotion_revenue": "$626.06",
        "seller_type": "BRAND",
        "shopping_mall_revenue": "$32.66k",
        "showcase_revenue": "$39.67k",
        "total": 500,
        "unit_price": "$55.85",
        "video_revenue": "$146.95k"
      },
      {
        "affiliate_revenue": "$32.13k",
        "id": "7495638404827024204",
        "is_full_service": 0,
        "live_revenue": "$13.74k",
        "main_category": {
          "pri_main_category": [
            "601450"
          ],
          "sec_main_category": [
            "601450-848648"
          ],
          "ter_main_category": [
            "601450-848648-601534"
          ]
        },
        "name": "The Lip Bar",
        "region": "US",
        "revenue": "$45.24k",
        "revenue_grouping_rate": "-18.3%",
        "revenue_trend": [
          690,
          1138
        ],
        "sale": 2784,
        "self_promotion_revenue": "$8.10k",
        "seller_type": "BRAND",
        "shopping_mall_revenue": "$5.02k",
        "showcase_revenue": "$7.76k",
        "total": 500,
        "unit_price": "$16.25",
        "video_revenue": "$23.73k"
      }
    ],
    "keyword": "lip oil",
    "market": "US",
    "next": "eyJwYWdlIjoyLCJzaXplIjozfQ",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "see_also": "Pass a row's id (sellerId) to shop: method=sales, trend, products, creators, or store for the live storefront.",
    "sortedBy": "revenue",
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totalMatched": 500,
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyLCJzaXplIjozfQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.items`array
- `data.items[].affiliate_revenue`string
- `data.items[].id`string
- `data.items[].is_full_service`integer
- `data.items[].live_revenue`string
- `data.items[].main_category`string
- `data.items[].name`string
- `data.items[].region`string
- `data.items[].revenue`string
- `data.items[].revenue_grouping_rate`string
- `data.items[].revenue_trend`array
- `data.items[].sale`integer
- `data.items[].self_promotion_revenue`string
- `data.items[].seller_type`string
- `data.items[].shopping_mall_revenue`string
- `data.items[].showcase_revenue`string
- `data.items[].total`integer
- `data.items[].unit_price`string
- `data.items[].video_revenue`string
- `data.keyword`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.see_also`string
- `data.sortedBy`string
- `data.source`string
- `data.totalMatched`integer
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Top-selling TikTok Shop creators

Shop Analytics

Creators (affiliates) ranked by the sales they drove over a date range: revenue, units, followers, engagement, views, trend. `keyword` matches creator names, handles and bios, not the products they sell; `category` takes a category name or id (levels 1 to 3: the creators selling in it, no keyword needed).

With neither, the result is the top 10 creators for the most recent days (about 6). Up to 100 rows per page with cursor paging, about 700 rows per keyword.

### [Creators ranked by sales](https://tokconnect.com/docs/api/rankings/#get-affiliates-top)

`GET /v1/affiliates/top`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `keyword` (string): Matched against creator names, handles and bios (not the products they sell): 'pet' finds accounts like 'Pet Finds'. For the affiliates of a product type, pass category, or rank products with [`GET /v1/products/top`](https://tokconnect.com/docs/api/rankings/#get-products-top) and call [`GET /v1/products/{id}/creators`](https://tokconnect.com/docs/api/products/#get-products-id-creators) on the top items. If keyword and category are both omitted, the result is the top 10 creators for the most recent days (about 6), whatever window is set: pass a keyword or category to get more than 10 rows or a specific window.
- `limit` (integer): Results per page. Max 100 per page; pass next as cursor for the following page. Up to about 700 rows per keyword. Without a keyword or category: 10 rows. Values above the maximum are lowered and reported in notes.

**18 more optional parameters**

- `account_type` (string): Filter. BELONGED_TO_SELLER = a brand's own account; INDEPENDENT = affiliate creator. **One of** `BELONGED_TO_SELLER` `INDEPENDENT`.
- `audience_age` (string): Filter. Main follower age band. **One of** `18-24` `25-34` `35-44` `45-54` `55+`.
- `audience_language` (string): Filter. Main follower language. **One of** `en-US` `es-ES` `pt-BR` `fr-FR` `de-DE` `it-IT` `ja-JP` `ru-RU`.
- `avg_views` (string): Filter. Average video views, e.g. >10000.
- `category` (array of string): Narrow to one or more Shop categories (up to 5), by name or numeric id, levels 1 to 3: "Skincare", "Pet Supplies", "Beauty & Personal Care","Health" or "601450". Without a keyword the creators of the category are found by merging several generic keyword searches (the Shop data needs a keyword), and the result says how many keyword sweeps and distinct rows that gave. Find names and ids with [`GET /v1/categories/tree`](https://tokconnect.com/docs/api/categories/#get-categories-tree).
- `contact` (string): Filter. Only creators who list this contact channel. Several: comma separated, e.g. EMAIL,INSTAGRAM. Values: EMAIL, WHATSAPP, INSTAGRAM, YOUTUBE, FACEBOOK, TWITTER.
- `debut` (string): Filter. Days since the creator started selling: <4, <8, <31, or >30. **One of** `<4` `<8` `<31` `>30`.
- `engagement` (string): Filter. Video engagement rate percent, e.g. >8.
- `followers` (string): Filter. Followers, e.g. 50000-500000.
- `gender` (string): Filter. Creator gender as the feed classifies it. **One of** `Female` `Male`.
- `growing` (boolean): Filter. true = only creators whose revenue is growing.
- `language` (string): Filter. Creator language. **One of** `en` `es` `pt` `fr` `zh` `de` `it`.
- `mcn` (string): Filter. Signed to an MCN (agency) or not. **One of** `SIGNED` `NOT_SIGNED`.
- `order` (string): desc (default, highest first) or asc (lowest first among the matching rows; pair it with a revenue or units filter to skip dead listings). Applies with a keyword or category. **One of** `desc` `asc`.
- `price` (string): Filter. Average price of what they sell, in the market's currency, e.g. <20.
- `revenue` (string): Filter. Revenue the creator drove in the market's currency over the window, e.g. >10000.
- `revenue_source` (string): Filter. Main revenue source: VIDEO or LIVE. **One of** `VIDEO` `LIVE`.
- `sort` (string): Ranking metric: followers, growth, revenue, units. Default revenue. growth favours brand-new items (shown as >999.9%); pair it with a revenue or units filter. Applies with a keyword or category. **One of** `followers` `growth` `revenue` `units`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_top_selling` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_top_selling",
  "arguments": {
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/affiliates/top?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/affiliates/top",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/affiliates/top?${params}`, {
  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:

```json
{
  "data": {
    "count": 3,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": true,
    "items": [
      {
        "creatorDebut": "2024-01-01",
        "followers": "10.5k",
        "handle": "creator_1",
        "id": "6805718817295614981",
        "main_category": {
          "pri_main_category": [
            "601352",
            "601152"
          ],
          "sec_main_category": [
            "601352-900488",
            "600154-808328"
          ],
          "ter_main_category": [
            "601352-900488-901000",
            "600154-808328-600157"
          ]
        },
        "new_followers": "0",
        "nickname": "Example creator 1",
        "revenue": "$15.23k",
        "revenue_grouping_rate": 3.1356722740088223,
        "revenue_trend": [
          29,
          317
        ],
        "sale": "558",
        "total": 500,
        "unit_price": "$27.29",
        "video_engagement_rate": "1.37%",
        "views": "411.13k",
        "views_trend": [
          5474,
          7337
        ]
      },
      {
        "creatorDebut": "2024-10-19",
        "followers": "7.8k",
        "handle": "creator_2",
        "id": "7397862193050485802",
        "main_category": {
          "pri_main_category": [
            "601450"
          ],
          "sec_main_category": [
            "601450-849160",
            "601450-856208"
          ],
          "ter_main_category": [
            "601450-849160-873736",
            "601450-856208-855952"
          ]
        },
        "new_followers": "211",
        "nickname": "Example creator 2",
        "revenue": "$9.71k",
        "revenue_grouping_rate": -0.18963460104399701,
        "revenue_trend": [
          952,
          0
        ],
        "sale": "206",
        "total": 500,
        "unit_price": "$47.14",
        "video_engagement_rate": "-",
        "views": "36.2k",
        "views_trend": [
          2614,
          105
        ]
      }
    ],
    "keyword": "lip oil",
    "market": "US",
    "next": "eyJwYWdlIjoyLCJzaXplIjozfQ",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "see_also": "Pass a row's id or handle to creator_commerce (sales, products, shops, audience) or creator (profile, posts).",
    "sortedBy": "revenue",
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totalMatched": 500,
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyLCJzaXplIjozfQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.items`array
- `data.items[].creatorDebut`string
- `data.items[].followers`string
- `data.items[].handle`string
- `data.items[].id`string
- `data.items[].main_category`string
- `data.items[].new_followers`string
- `data.items[].nickname`string
- `data.items[].revenue`string
- `data.items[].revenue_grouping_rate`number
- `data.items[].revenue_trend`array
- `data.items[].sale`string
- `data.items[].signature`string
- `data.items[].total`integer
- `data.items[].unit_price`string
- `data.items[].video_engagement_rate`string
- `data.items[].views`string
- `data.items[].views_trend`array
- `data.keyword`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.see_also`string
- `data.sortedBy`string
- `data.source`string
- `data.totalMatched`integer
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Top-selling TikTok Shop videos

Shop Analytics

The top 10 shoppable videos by estimated revenue over a date range, with revenue, units, views, GPM, ad metrics (CPA, ROAS, ad revenue share), whether it is AI-generated, and the creator. This ranking takes no filters; to study one niche, rank its products with [`GET /v1/products/top`](https://tokconnect.com/docs/api/rankings/#get-products-top), then call [`GET /v1/products/{id}/video-sales`](https://tokconnect.com/docs/api/products/#get-products-id-video-sales). Pass a row's id to [`GET /v1/videos/{id}/transcript`](https://tokconnect.com/docs/api/videos/#get-videos-id-transcript) or [`GET /v1/videos/{id}/products`](https://tokconnect.com/docs/api/videos/#get-videos-id-products).

### [Top videos by sales](https://tokconnect.com/docs/api/rankings/#get-videos-top-selling)

`GET /v1/videos/top-selling`

1 credit per call · Shop Analytics · 17 markets

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/rankings/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video_top_selling` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video_top_selling",
  "arguments": {}
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/top-selling" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/top-selling", {
  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:

```json
{
  "data": {
    "count": 10,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": false,
    "items": [
      {
        "ad": 1,
        "ad2Cost": "$25.73k",
        "ad2Roas": 3.69,
        "ad_cpa": "$82.20",
        "ad_revenue_ratio": "80.00%",
        "ad_view_ratio": "28.88%",
        "ai_video": 0,
        "collect_day": "2026-10-25",
        "content_type": "video",
        "creator_uid": "7408927728046933038",
        "description": "I think there’s a clear winner here 😅 #vacuum #stickvacuum #petallergies #shark #sharkpowerproflex ",
        "duration": "1m 35s",
        "follower_count": "191.3k",
        "gpm": "$51.56",
        "handle": "kid.shops",
        "id": "7700682843906723103",
        "original_duration": 95.267,
        "publish_date": "2026/10/25 15:02:39",
        "revenue": "$118.63k",
        "revenueDiff": 11786900,
        "revenue_grouping_rate": -2.0203332575437685,
        "revenue_trend": [
          0,
          0
        ],
        "sale": 313,
        "views": "2.3m",
        "views_trend": [
          0,
          0
        ]
      },
      {
        "ad": 1,
        "ad2Cost": "$23.83k",
        "ad2Roas": 3.53,
        "ad_cpa": "$77.61",
        "ad_revenue_ratio": "72.70%",
        "ad_view_ratio": "22.75%",
        "ai_video": 0,
        "collect_day": "2026-02-17",
        "content_type": "video",
        "creator_uid": "6546693901460832266",
        "description": "Changed my life. ",
        "duration": "2m 41s",
        "follower_count": "5m",
        "gpm": "$42.52",
        "handle": "_jen_hamilton_",
        "id": "7607862589363670285",
        "original_duration": 161.767,
        "publish_date": "2026/02/17 10:53:10",
        "revenue": "$115.74k",
        "revenueDiff": -9613500,
        "revenue_grouping_rate": -1.9762080055798814,
        "revenue_trend": [
          84825,
          16211
        ],
        "sale": 307,
        "views": "2.72m",
        "views_trend": [
          778386,
          334822
        ]
      }
    ],
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD.",
      "Without a keyword TikTok Shop data returns its fixed overall top 10 for the most recent days (window below), whatever window you ask for. Add a keyword to rank more rows over your own window."
    ],
    "see_also": "Pass a row's id to video: method=detail, transcript, products, sales.",
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 6,
      "end": "2026-10-28",
      "start": "2026-10-23"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.items`array
- `data.items[].ad`integer
- `data.items[].ad2Cost`string
- `data.items[].ad2Roas`number
- `data.items[].ad_cpa`string
- `data.items[].ad_revenue_ratio`string
- `data.items[].ad_view_ratio`string
- `data.items[].ai_video`integer
- `data.items[].collect_day`string
- `data.items[].content_type`string
- `data.items[].creator_uid`string
- `data.items[].description`string
- `data.items[].duration`string
- `data.items[].follower_count`string
- `data.items[].gpm`string
- `data.items[].handle`string
- `data.items[].id`string
- `data.items[].original_duration`number
- `data.items[].publish_date`string
- `data.items[].revenue`string
- `data.items[].revenueDiff`integer
- `data.items[].revenue_grouping_rate`number
- `data.items[].revenue_trend`array
- `data.items[].sale`integer
- `data.items[].views`string
- `data.items[].views_trend`array
- `data.market`string
- `data.notes`array
- `data.see_also`string
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Top-selling TikTok Shop LIVEs

Shop Analytics

The top 10 LIVE broadcasts by estimated revenue over a date range, with host, start and end time, duration, units, GPM and average price. This ranking takes no filters. Pass a row's id to the routes under [`GET /v1/lives/{id}`](https://tokconnect.com/docs/api/live/#get-lives-id).

### [Top LIVEs by sales](https://tokconnect.com/docs/api/rankings/#get-lives-top-selling)

`GET /v1/lives/top-selling`

1 credit per call · Shop Analytics · 17 markets

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/rankings/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `live_top_selling` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "live_top_selling",
  "arguments": {}
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/lives/top-selling" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/lives/top-selling", {
  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:

```json
{
  "data": {
    "count": 10,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": false,
    "items": [
      {
        "create_time": "2026/10/21 06:15:53",
        "duration": "123h 56m",
        "finish_time": "2026/10/26 10:12:51",
        "gpm": "$55.39",
        "handle": "based",
        "id": "7699061230417349407",
        "main_category": [
          "601450-848904"
        ],
        "record_type": "SHORT",
        "revenue": "$169.85k",
        "sale": 5694,
        "title": "DEALS FOR YOU - Live Now!",
        "uid": "7153432386608251946",
        "unit_price": "$29.83",
        "views": "3.07m"
      },
      {
        "create_time": "2026/10/25 15:40:57",
        "duration": "11h 39m",
        "finish_time": "2026/10/26 03:20:04",
        "gpm": "$763.53",
        "handle": "glamourmodernfashion1",
        "id": "7700692389735811853",
        "main_category": [
          "601152-842376"
        ],
        "record_type": "SHORT",
        "revenue": "$89.92k",
        "sale": 1251,
        "title": "",
        "uid": "7043091206013060102",
        "unit_price": "$71.88",
        "views": "117.77k"
      },
      {
        "create_time": "2026/10/27 18:27:37",
        "duration": "5h 57m",
        "finish_time": "2026/10/28 00:25:29",
        "gpm": "$816.49",
        "handle": "noelyfajas",
        "id": "7701477528661920543",
        "main_category": [
          "601152-842888"
        ],
        "record_type": "SHORT",
        "revenue": "$82.50k",
        "sale": 969,
        "title": "Fall Deals For You LIVE",
        "uid": "6801519791112897542",
        "unit_price": "$85.13",
        "views": "101.04k"
      }
    ],
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD.",
      "Without a keyword TikTok Shop data returns its fixed overall top 10 for the most recent days (window below), whatever window you ask for. Add a keyword to rank more rows over your own window."
    ],
    "see_also": "Pass a row's id to live: method=products, sales, history.",
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 8,
      "end": "2026-10-28",
      "start": "2026-10-21"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.items`array
- `data.items[].create_time`string
- `data.items[].duration`string
- `data.items[].finish_time`string
- `data.items[].gpm`string
- `data.items[].handle`string
- `data.items[].id`string
- `data.items[].main_category`array
- `data.items[].record_type`string
- `data.items[].revenue`string
- `data.items[].sale`integer
- `data.items[].title`string
- `data.items[].uid`string
- `data.items[].unit_price`string
- `data.items[].views`string
- `data.market`string
- `data.notes`array
- `data.see_also`string
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/rankings/

---

# TikTok Shop products API

Everything about one TikTok Shop product: live price and stock, sales, daily trend, the creators and videos selling it, and what reviews say. Plus the store as shoppers see it now.

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

Call these routes with your own key, or ask the same question in plain words.

[Get an API key](https://app.tokconnect.com/api-key)[Use it in ChatGPT or Claude](https://app.tokconnect.com/mcp?app=chatgpt)[Ask: which creators sell the most lip gloss on TikTok Shop US, and what do reviewers complain about?](https://app.tokconnect.com/?q=Which%20creators%20sell%20the%20most%20lip%20gloss%20on%20TikTok%20Shop%20US%2C%20and%20what%20do%20reviewers%20complain%20about%3F)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/products/{id}`](https://tokconnect.com/docs/api/products/#get-products-id) | Live price, SKUs and stock, sold, rating, shop |
| [GET `/v1/products/{id}/analysis`](https://tokconnect.com/docs/api/products/#get-products-id-analysis) | Selling-point highlights and attributes TokConnect extracts for the product |
| [GET `/v1/products/{id}/conversion`](https://tokconnect.com/docs/api/products/#get-products-id-conversion) | How many creators promote it and what share of them made sales |
| [GET `/v1/products/{id}/creators`](https://tokconnect.com/docs/api/products/#get-products-id-creators) | Creators selling it, ranked, with revenue |
| [GET `/v1/products/{id}/related`](https://tokconnect.com/docs/api/products/#get-products-id-related) | Products TikTok shows as related |
| [GET `/v1/products/{id}/review-insights`](https://tokconnect.com/docs/api/products/#get-products-id-review-insights) | AI summary of reviews: pain points, praise, use cases (by_sku splits by variant) |
| [GET `/v1/products/{id}/reviews`](https://tokconnect.com/docs/api/products/#get-products-id-reviews) | Public reviews |
| [GET `/v1/products/{id}/sales`](https://tokconnect.com/docs/api/products/#get-products-id-sales) | Revenue, units, video/LIVE/showcase split, creator count, conversion (ids: up to 20 products) |
| [GET `/v1/products/{id}/skus`](https://tokconnect.com/docs/api/products/#get-products-id-skus) | Sales by variant (SKU) |
| [GET `/v1/products/{id}/trend`](https://tokconnect.com/docs/api/products/#get-products-id-trend) | Daily revenue and units (up to ~13 months) |
| [GET `/v1/products/{id}/video-sales`](https://tokconnect.com/docs/api/products/#get-products-id-video-sales) | Videos selling it, with revenue |
| [GET `/v1/products/{id}/videos`](https://tokconnect.com/docs/api/products/#get-products-id-videos) | The videos on the product page (first page only) |
| [GET `/v1/storefront/category-page`](https://tokconnect.com/docs/api/products/#get-storefront-category-page) | A category page (category_id + slug) |
| [GET `/v1/storefront/deals`](https://tokconnect.com/docs/api/products/#get-storefront-deals) | The deals feed |
| [GET `/v1/storefront/flash-sales`](https://tokconnect.com/docs/api/products/#get-storefront-flash-sales) | Flash sales |
| [GET `/v1/storefront/keyword-page`](https://tokconnect.com/docs/api/products/#get-storefront-keyword-page) | An SEO keyword page (slug) |
| [GET `/v1/storefront/page`](https://tokconnect.com/docs/api/products/#get-storefront-page) | Any other Shop page by path |
| [GET `/v1/storefront/search`](https://tokconnect.com/docs/api/products/#get-storefront-search) | Shop search results |

## Common parameters

These read the same on the routes below that take them.

- `region` (string): Market as an ISO country code, default US. Amounts are in the market's currency. See [Markets](https://tokconnect.com/docs/api/markets/).
- `window` (string): Date range ending at the last complete day (about 2 days ago). Default 30d. Use start and end for a custom range. **One of** `7d` `30d` `90d` `180d` `365d`.
- `start` (string): Custom range start, YYYY-MM-DD.
- `end` (string): Custom range end, YYYY-MM-DD (capped at the last complete day).
- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## One TikTok Shop product

Everything about one TikTok Shop product (id = product id or a Shop product link). Live from TikTok: page (price, SKUs and stock, rating, shop, and sold = TikTok's displayed lifetime units), reviews, related products and page videos.

From Shop Analytics, in any market via region: sales, trend (daily), creators, video sales, SKUs, analysis (highlights and attributes), conversion (creators promoting it and the share who sold) and review insights (complaints, praise, use cases; `by_sku` splits by variant).

### [Live price, SKUs and stock, sold, rating, shop](https://tokconnect.com/docs/api/products/#get-products-id)

`GET /v1/products/{id}`

1 credit per call · 17 markets

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: page`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "page",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226", {
  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:

```json
{
  "data": {
    "categories": [
      "Beauty & Personal Care"
    ],
    "currency": "USD",
    "delivery": "3-day delivery",
    "id": "1731896769144001226",
    "moreFromShop": [
      {
        "brand": "Truly Beauty",
        "currency": "USD",
        "id": "1729389462563361482",
        "price": 33,
        "rating": 4.4,
        "reviews": 9993,
        "sellerId": "7495153913553128138",
        "shop": "Truly Beauty",
        "sold": 81325,
        "title": "Glazed Donut Brightening Oil – Discoloration-Fighting Treatment – Brightens Dull, Uneven Skin with Vitamin E, Niacinamide & Hyaluronic Acid – Deeply Hydrates, Minimizes Ingrowns & Enhances Radiance on Legs, Underarms & Bikini Line –…",
        "url": "https://shop.tiktok.com/us/pdp/after-shave-oil-by-truly-beauty-glazed-donut-hydrating-serum/1729389462563361482"
      }
    ],
    "price": 13.92,
    "rating": 4.5,
    "relatedProducts": [
      {
        "brand": "Truly Beauty",
        "currency": "USD",
        "discount": "52%",
        "id": "1731896769144001226",
        "originalPrice": 29,
        "price": 13.92,
        "rating": 4.5,
        "reviews": 14794,
        "sellerId": "7495153913553128138",
        "shop": "Truly Beauty",
        "sold": 153726,
        "title": "Hydrating Lip Gloss - High Shine & Tinted, Infused with Hyaluronic Acid, Jojoba Oil & Shea Butter",
        "url": "https://shop.tiktok.com/us/pdp/hydrating-lip-gloss-high-shine-tinted-hyaluronic-acid/1731896769144001226"
      }
    ],
    "reviews": 14794,
    "sellerId": "7495153913553128138",
    "shop": "Truly Beauty",
    "shopInfo": {
      "name": "Truly Beauty",
      "products": 49,
      "rating": 4.4,
      "sellerId": "7495153913553128138",
      "sold": 1786361
    },
    "skus": [
      {
        "id": "1731896802257769162",
        "inStock": true,
        "price": 13.92,
        "variant": "Soft Serve"
      }
    ],
    "sold": 153726,
    "title": "Hydrating Lip Gloss - High Shine & Tinted, Infused with Hyaluronic Acid, Jojoba Oil & Shea Butter",
    "url": "https://www.tiktok.com/view/product/1731896769144001226",
    "videos": [
      {
        "caption": "The definition of a high shine gloss!😍🤏🏽🫦#trulylipgloss #trulybeauty #tiktokshopstockup #tiktokshopcreatorpicks #tiktokshopmothersday",
        "creatorId": "7384276485555094570",
        "creatorName": "Peta🎀",
        "durationSec": 32.2,
        "earnsCommission": true,
        "likes": 72013,
        "posted": "2026-04-30T04:39:25Z",
        "videoId": "7634407159618489630",
        "views": 6015574
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.categories`array
- `data.currency`string
- `data.delivery`string
- `data.id`string
- `data.moreFromShop`array
- `data.moreFromShop[].brand`string
- `data.moreFromShop[].currency`string
- `data.moreFromShop[].id`string
- `data.moreFromShop[].price`integer
- `data.moreFromShop[].rating`number
- `data.moreFromShop[].reviews`integer
- `data.moreFromShop[].sellerId`string
- `data.moreFromShop[].shop`string
- `data.moreFromShop[].sold`integer
- `data.moreFromShop[].title`string
- `data.moreFromShop[].url`string
- `data.price`number
- `data.rating`number
- `data.relatedProducts`array
- `data.relatedProducts[].brand`string
- `data.relatedProducts[].currency`string
- `data.relatedProducts[].discount`string
- `data.relatedProducts[].id`string
- `data.relatedProducts[].originalPrice`integer
- `data.relatedProducts[].price`number
- `data.relatedProducts[].rating`number
- `data.relatedProducts[].reviews`integer
- `data.relatedProducts[].sellerId`string
- `data.relatedProducts[].shop`string
- `data.relatedProducts[].sold`integer
- `data.relatedProducts[].title`string
- `data.relatedProducts[].url`string
- `data.reviews`integer
- `data.sellerId`string
- `data.shop`string
- `data.shopInfo`object
- `data.shopInfo.name`string
- `data.shopInfo.products`integer
- `data.shopInfo.rating`number
- `data.shopInfo.sellerId`string
- `data.shopInfo.sold`integer
- `data.skus`array
- `data.skus[].id`string
- `data.skus[].inStock`boolean
- `data.skus[].price`number
- `data.skus[].variant`string
- `data.sold`integer
- `data.title`string
- `data.url`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].creatorId`string
- `data.videos[].creatorName`string
- `data.videos[].durationSec`number
- `data.videos[].earnsCommission`boolean
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].videoId`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Selling-point highlights and attributes TokConnect extracts for the product](https://tokconnect.com/docs/api/products/#get-products-id-analysis)

`GET /v1/products/{id}/analysis`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: analysis`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "analysis",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/analysis" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/analysis", {
  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:

```json
{
  "data": {
    "analysis": {
      "attributes": [
        {
          "key": "Skin Type",
          "value": "All Skin Types"
        },
        {
          "key": "Region Of Origin",
          "value": "US"
        },
        {
          "key": "Product Form",
          "value": "Liquid"
        }
      ],
      "highlights": [
        {
          "key_word": "Lasting Hydration",
          "region_text": "Lasting Hydration: Lips stay soft, smooth, and quenched for hours."
        },
        {
          "key_word": "High-Shine Finish",
          "region_text": "High-Shine Finish: Glossy, light-catching lips that feel luxurious."
        },
        {
          "key_word": "Instant Relief",
          "region_text": "Instant Relief: Dry, chapped lips feel soothed from the first swipe."
        }
      ]
    },
    "dataEnd": "2026-10-28",
    "id": "1731896769144001226",
    "market": "US",
    "notes": [
      "Market US (United States)."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.analysis`object
- `data.analysis.attributes`array
- `data.analysis.attributes[].key`string
- `data.analysis.attributes[].value`string
- `data.analysis.highlights`array
- `data.analysis.highlights[].key_word`string
- `data.analysis.highlights[].region_text`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [How many creators promote it and what share of them made sales](https://tokconnect.com/docs/api/products/#get-products-id-conversion)

`GET /v1/products/{id}/conversion`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: conversion`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "conversion",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/conversion" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/conversion", {
  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:

```json
{
  "data": {
    "conversion": {
      "creatorConversionRatio": 0.47589952477936187,
      "creatorNum": 1473
    },
    "creatorConversionPercent": 47.6,
    "creatorConversionRatio": 0.47589952477936187,
    "creators": 1473,
    "dataEnd": "2026-10-28",
    "id": "1731896769144001226",
    "market": "US",
    "notes": [
      "Market US (United States).",
      "creatorConversionRatio is the source's share of the creators promoting this product who made a sale in the window, as a fraction (0.59 means 59%)."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.conversion`object
- `data.conversion.creatorConversionRatio`number
- `data.conversion.creatorNum`integer
- `data.creatorConversionPercent`number
- `data.creatorConversionRatio`number
- `data.creators`integer
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Creators selling it, ranked, with revenue](https://tokconnect.com/docs/api/products/#get-products-id-creators)

`GET /v1/products/{id}/creators`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: creators`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "creators",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/creators" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/creators", {
  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:

```json
{
  "data": {
    "count": 20,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": true,
    "id": "1731896769144001226",
    "items": [
      {
        "followers": 23600,
        "handle": "creator_1",
        "id": "6790832707742417925",
        "live_revenue": "$0.00",
        "nickname": "Example creator 1",
        "revenue": "$58.12k",
        "sale": "7.27k",
        "video_revenue": "$58.12k"
      },
      {
        "followers": 19400,
        "handle": "creator_2",
        "id": "7384276485555094570",
        "live_revenue": "$0.00",
        "nickname": "Example creator 2",
        "revenue": "$37.02k",
        "sale": "4.63k",
        "video_revenue": "$37.02k"
      },
      {
        "followers": 17400,
        "handle": "creator_3",
        "id": "6672578604607685638",
        "live_revenue": "$0.00",
        "nickname": "Example creator 3",
        "revenue": "$36.01k",
        "sale": "4.5k",
        "video_revenue": "$36.01k"
      }
    ],
    "market": "US",
    "next": "eyJwYWdlIjoyLCJzaXplIjoyMH0",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyLCJzaXplIjoyMH0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.id`string
- `data.items`array
- `data.items[].followers`integer
- `data.items[].handle`string
- `data.items[].id`string
- `data.items[].live_revenue`string
- `data.items[].nickname`string
- `data.items[].revenue`string
- `data.items[].sale`string
- `data.items[].video_revenue`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Products TikTok shows as related](https://tokconnect.com/docs/api/products/#get-products-id-related)

`GET /v1/products/{id}/related`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: related`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "related",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/related" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/related", {
  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:

```json
{
  "data": {
    "hasMore": false,
    "page": "related",
    "products": [
      {
        "brand": "Truly Beauty",
        "currency": "USD",
        "discount": "52%",
        "id": "1731896769144001226",
        "originalPrice": 29,
        "price": 13.92,
        "rating": 4.5,
        "reviews": 14778,
        "sellerId": "7495153913553128138",
        "shop": "Truly Beauty",
        "sold": 153728,
        "title": "Hydrating Lip Gloss - High Shine & Tinted, Infused with Hyaluronic Acid, Jojoba Oil & Shea Butter",
        "url": "https://shop.tiktok.com/us/pdp/hydrating-lip-gloss-high-shine-tinted-hyaluronic-acid/1731896769144001226"
      },
      {
        "brand": "Colourpop Cosmetics LLC",
        "currency": "USD",
        "id": "1730162690572390449",
        "price": 12.99,
        "rating": 4.8,
        "reviews": 4092,
        "sellerId": "7495294719207180337",
        "shop": "ColourPop Cosmetics",
        "sold": 45759,
        "title": "ColourPop Fresh Kiss Glossy Balm - Peptides & Hyaluronic Acid",
        "url": "https://shop.tiktok.com/us/pdp/glossy-lip-balm-by-colourpop-fresh-kiss-with-peptides-hyaluronic-acid/1730162690572390449"
      },
      {
        "brand": "Laneige",
        "currency": "USD",
        "id": "1729424048269136205",
        "price": 24.7,
        "rating": 4.8,
        "reviews": 2000,
        "sellerId": "7495286718562273613",
        "shop": "Laneige US",
        "sold": 6367,
        "title": "Laneige Lip Glowy Balm, Hydrating and Glossy Tinted Lip Care with Shea Butter, Korean Skincare, Lightweight Moisturizer",
        "url": "https://shop.tiktok.com/us/pdp/lip-glowy-balm-by-laneige-us-moisture-rich-hydrating-treatment/1729424048269136205"
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.page`string
- `data.products`array
- `data.products[].brand`string
- `data.products[].currency`string
- `data.products[].discount`string
- `data.products[].id`string
- `data.products[].originalPrice`integer
- `data.products[].price`number
- `data.products[].rating`number
- `data.products[].reviews`integer
- `data.products[].sellerId`string
- `data.products[].shop`string
- `data.products[].sold`integer
- `data.products[].title`string
- `data.products[].url`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [AI summary of reviews: pain points, praise, use cases (by_sku splits by variant)](https://tokconnect.com/docs/api/products/#get-products-id-review-insights)

`GET /v1/products/{id}/review-insights`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**2 more optional parameters**

- `by_sku` (boolean): Split insights by SKU. **Default**`false`.
- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: review_insights`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "review_insights",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/review-insights" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/review-insights", {
  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:

```json
{
  "data": {
    "dataEnd": "2026-10-28",
    "id": "1731896769144001226",
    "insights": {
      "badRate": "11.0%",
      "commentSummary": "This lip gloss is praised for its hydrating, non-sticky texture, beautiful range of colors, high shine, and appealing packaging. Many users highlight its smooth application and lightweight feel. However, a significant number of customers…",
      "goodRate": "89.0%",
      "painPoints": [
        {
          "point": "Tube is half-empty or missing product",
          "quotes": [
            {
              "date": "2026/04/10",
              "rating": "1.0",
              "sku": "Coco Cloud",
              "text": "I don't know if it's air in the tube that prevents them from filling the tube but I feel like I got robbed! The tube is already small but its only filled half way. My lips did feel moisturized...they felt wet! 0 out of 10. I do NOT…"
            }
          ],
          "rate": "28.33%",
          "reviews": 17
        }
      ],
      "positivePoints": [
        {
          "point": "Very hydrating and moisturizing",
          "quotes": [
            {
              "date": "2026/04/10",
              "rating": "5.0",
              "sku": "Vanilla Baby",
              "text": "This gloss is amazing! It is so hydrating and makes my lips feel great. I want to get every one they have now."
            }
          ],
          "rate": "22.47%",
          "reviews": 20
        }
      ],
      "productRating": null,
      "skuNames": [
        "Vanilla Baby"
      ],
      "usageFrequency": [
        {
          "point": "Multiple times a day",
          "quotes": [
            {
              "date": "2026/04/11",
              "rating": "5.0",
              "sku": "Soft Serve",
              "text": "These are really amazing. They are really hydrating with a pop of color. I have one on my desk and apply several times throughout the day."
            }
          ],
          "rate": "33.33%",
          "reviews": 1
        }
      ],
      "usageLocation": [
        {
          "point": "At work/desk",
          "quotes": [
            {
              "date": "2026/04/13",
              "rating": "5.0",
              "sku": "Soft Serve",
              "text": "Love! The colors great and it so cute at my desk .😊"
            }
          ],
          "rate": "66.67%",
          "reviews": 2
        }
      ],
      "usageScenarios": [
        {
          "point": "Daily lip care and hydration",
          "quotes": [
            {
              "date": "2026/04/11",
              "rating": "5.0",
              "sku": "Soft Serve",
              "text": "These are really amazing. They are really hydrating with a pop of color. I have one on my desk and apply several times throughout the day."
            }
          ],
          "rate": "41.67%",
          "reviews": 5
        }
      ]
    },
    "market": "US",
    "notes": [
      "Market US (United States)."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.dataEnd`string
- `data.id`string
- `data.insights`object
- `data.insights.badRate`string
- `data.insights.commentSummary`string
- `data.insights.goodRate`string
- `data.insights.painPoints`array
- `data.insights.painPoints[].point`string
- `data.insights.painPoints[].quotes`array
- `data.insights.painPoints[].rate`string
- `data.insights.painPoints[].reviews`integer
- `data.insights.positivePoints`array
- `data.insights.positivePoints[].point`string
- `data.insights.positivePoints[].quotes`array
- `data.insights.positivePoints[].rate`string
- `data.insights.positivePoints[].reviews`integer
- `data.insights.productRating`null
- `data.insights.skuNames`array
- `data.insights.usageFrequency`array
- `data.insights.usageFrequency[].point`string
- `data.insights.usageFrequency[].quotes`array
- `data.insights.usageFrequency[].rate`string
- `data.insights.usageFrequency[].reviews`integer
- `data.insights.usageLocation`array
- `data.insights.usageLocation[].point`string
- `data.insights.usageLocation[].quotes`array
- `data.insights.usageLocation[].rate`string
- `data.insights.usageLocation[].reviews`integer
- `data.insights.usageScenarios`array
- `data.insights.usageScenarios[].point`string
- `data.insights.usageScenarios[].quotes`array
- `data.insights.usageScenarios[].rate`string
- `data.insights.usageScenarios[].reviews`integer
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Public reviews](https://tokconnect.com/docs/api/products/#get-products-id-reviews)

`GET /v1/products/{id}/reviews`

1 credit per call · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**5 more optional parameters**

- `filter` (string): All (default), `with_media` or verified. **One of** `all` `with_media` `verified`.
- `limit` (integer): Results per page. Max 5. Values above the maximum are lowered and reported in notes.
- `page` (integer): Jump to this page (1-100).
- `sort` (string): Recommended (default) or newest. **One of** `recommended` `newest`.
- `stars` (string): Star filter when `filter=all`. **One of** `all` `5` `4` `3` `2` `1`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: reviews`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "reviews",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/reviews" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/reviews", {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJwYWdlX3N0YXJ0IjoyfQ",
    "page": "reviews",
    "reviews": [
      {
        "country": "US",
        "id": "7689521632322307854",
        "images": 4,
        "posted": "2026-09-25T17:11:15Z",
        "rating": 5,
        "reviewer": "T**s C**",
        "text": "The color pigment and texture is amazing.  My favorite New lipgloss to wear.   And keep in my purse to grab. Go get yours now!",
        "variant": "Vanilla Baby",
        "verifiedPurchase": true
      },
      {
        "country": "US",
        "id": "7689520290272118542",
        "images": 4,
        "posted": "2026-09-25T17:06:03Z",
        "rating": 5,
        "reviewer": "T**s C**",
        "text": "Shipping was FREE and FAST! The product and packaging was just as described so run don’t walk to purchase.  Already ordered my second batch of lipglosses.",
        "variant": "Glazed Donut",
        "verifiedPurchase": true
      },
      {
        "country": "US",
        "id": "7627673224491321102",
        "images": 4,
        "posted": "2026-04-12T01:08:26Z",
        "rating": 5,
        "reviewer": "J**8",
        "text": "They  both smell great . Coco cloud it Glades on smoothly. The shine is given rich glass . An number  It not sticky at all",
        "variant": "Coco Cloud",
        "verifiedPurchase": true
      }
    ],
    "source": "https://shop.tiktok.com/us/pdp/1731896769144001226",
    "totalReviews": 14794
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlX3N0YXJ0IjoyfQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.page`string
- `data.reviews`array
- `data.reviews[].country`string
- `data.reviews[].id`string
- `data.reviews[].images`integer
- `data.reviews[].posted`string
- `data.reviews[].rating`integer
- `data.reviews[].reviewer`string
- `data.reviews[].text`string
- `data.reviews[].variant`string
- `data.reviews[].verifiedPurchase`boolean
- `data.source`string
- `data.totalReviews`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Revenue, units, video/LIVE/showcase split, creator count, conversion (ids: up to 20 products)](https://tokconnect.com/docs/api/products/#get-products-id-sales)

`GET /v1/products/{id}/sales`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**2 more optional parameters**

- `ids` (array of string): [`GET /v1/products/{id}/sales`](https://tokconnect.com/docs/api/products/#get-products-id-sales) only: up to 20 product ids in one call.
- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: sales`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "sales",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/sales" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/sales", {
  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:

```json
{
  "data": {
    "creatorConversion": {
      "creatorConversionRatio": 0.47589952477936187,
      "creatorNum": 1473
    },
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "1731896769144001226",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totals": {
      "creatorConversionRatio": 0.47589952477936187,
      "day_live_revenue": "$185.43",
      "day_revenue": "$10.19k",
      "day_sale": "1.27k",
      "day_shopping_mall_revenue": "$4.00",
      "day_video_revenue": "$10.00k",
      "live_revenue": "$5.19k",
      "original_live_revenue": 5192,
      "original_revenue": 285280,
      "original_shopping_mall_revenue": 112,
      "original_video_revenue": 279976,
      "related_creator_count": 702,
      "revenue": "$285.28k",
      "sale": "35.66k",
      "shopping_mall_revenue": "$112.00",
      "unit_price": "$8.00",
      "video_revenue": "$279.98k"
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.creatorConversion`object
- `data.creatorConversion.creatorConversionRatio`number
- `data.creatorConversion.creatorNum`integer
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.totals`object
- `data.totals.creatorConversionRatio`number
- `data.totals.day_live_revenue`string
- `data.totals.day_revenue`string
- `data.totals.day_sale`string
- `data.totals.day_shopping_mall_revenue`string
- `data.totals.day_video_revenue`string
- `data.totals.live_revenue`string
- `data.totals.original_live_revenue`integer
- `data.totals.original_revenue`integer
- `data.totals.original_shopping_mall_revenue`integer
- `data.totals.original_video_revenue`integer
- `data.totals.related_creator_count`integer
- `data.totals.revenue`string
- `data.totals.sale`string
- `data.totals.shopping_mall_revenue`string
- `data.totals.unit_price`string
- `data.totals.video_revenue`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Sales by variant (SKU)](https://tokconnect.com/docs/api/products/#get-products-id-skus)

`GET /v1/products/{id}/skus`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: skus`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "skus",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/skus" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/skus", {
  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:

```json
{
  "data": {
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "1731896769144001226",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "skus": {
      "skus": [
        {
          "price_val": "$13.92",
          "sales_proportion": 0.3527,
          "sku_id": "1731896802257769162",
          "sku_name": "Shade:Soft Serve",
          "stock": 29142,
          "stock_share_proportion": 0.5678
        },
        {
          "price_val": "$13.92",
          "sales_proportion": 0.2488,
          "sku_id": "1731896802257834698",
          "sku_name": "Shade:Glazed Donut",
          "stock": 926,
          "stock_share_proportion": 0.018
        },
        {
          "price_val": "$13.92",
          "sales_proportion": 0.2156,
          "sku_id": "1731896802257900234",
          "sku_name": "Shade:Vanilla Baby",
          "stock": 20765,
          "stock_share_proportion": 0.4046
        }
      ],
      "updated_at": "2026-09-24"
    },
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.skus`object
- `data.skus.skus`array
- `data.skus.skus[].price_val`string
- `data.skus.skus[].sales_proportion`number
- `data.skus.skus[].sku_id`string
- `data.skus.skus[].sku_name`string
- `data.skus.skus[].stock`integer
- `data.skus.skus[].stock_share_proportion`number
- `data.skus.updated_at`string
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Daily revenue and units (up to ~13 months)](https://tokconnect.com/docs/api/products/#get-products-id-trend)

`GET /v1/products/{id}/trend`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: trend`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "trend",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/trend" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/trend", {
  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:

```json
{
  "data": {
    "coverage": {
      "days": 30,
      "daysWithSales": 28,
      "firstDayWithSales": "2026-09-29"
    },
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "1731896769144001226",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "series": [
      {
        "creatorConversionRatio": 0.2676923076923077,
        "live_revenue": 120,
        "partition_day": "2026-09-29",
        "revenue": 4760,
        "sale": 595,
        "unit_price": 8,
        "video_revenue": 4640
      },
      {
        "creatorConversionRatio": 0,
        "live_revenue": 0,
        "partition_day": "2026-09-30",
        "revenue": 0,
        "sale": 0,
        "unit_price": 8,
        "video_revenue": 0
      },
      {
        "creatorConversionRatio": 0,
        "live_revenue": 0,
        "partition_day": "2026-10-01",
        "revenue": 0,
        "sale": 0,
        "unit_price": 8,
        "video_revenue": 0
      }
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totals": {
      "revenue": 285280,
      "units": 35660
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.coverage`object
- `data.coverage.days`integer
- `data.coverage.daysWithSales`integer
- `data.coverage.firstDayWithSales`string
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.series`array
- `data.series[].creatorConversionRatio`number
- `data.series[].live_revenue`integer
- `data.series[].partition_day`string
- `data.series[].revenue`integer
- `data.series[].sale`integer
- `data.series[].unit_price`integer
- `data.series[].video_revenue`integer
- `data.source`string
- `data.totals`object
- `data.totals.revenue`integer
- `data.totals.units`integer
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Videos selling it, with revenue](https://tokconnect.com/docs/api/products/#get-products-id-video-sales)

`GET /v1/products/{id}/video-sales`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: video_sales`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "video_sales",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/video-sales" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/video-sales", {
  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:

```json
{
  "data": {
    "count": 20,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": true,
    "id": "1731896769144001226",
    "items": [
      {
        "ad": 1,
        "ads": 1,
        "ai_video": 0,
        "content_type": "video",
        "create_time": "2026/09/29 17:49:11",
        "description": "Obsessed with this #lipgloss #drylips #lipcombo ",
        "duration": "37s",
        "id": "7691077500054637838",
        "original_duration": 37.867,
        "revenue": "$24.90k",
        "sale": "3.11k",
        "views": "3.42m"
      },
      {
        "ad": 1,
        "ads": 1,
        "ai_video": 0,
        "content_type": "video",
        "create_time": "2026/09/21 22:58:40",
        "description": "Now this is how you do a high shine gloss!😍🤏🏽🫦✨#trulylipgloss #trulybeauty #lipgloss #tiktokshopstockup ",
        "duration": "42s",
        "id": "7688188610041957662",
        "original_duration": 42.9,
        "revenue": "$23.14k",
        "sale": "2.89k",
        "views": "3.3m"
      },
      {
        "ad": 1,
        "ads": 1,
        "ai_video": 0,
        "content_type": "video",
        "create_time": "2026/09/28 22:42:36",
        "description": "",
        "duration": "41s",
        "id": "7690782072524393759",
        "original_duration": 41.145,
        "revenue": "$20.91k",
        "sale": "2.61k",
        "views": "3.3m"
      }
    ],
    "market": "US",
    "next": "eyJwYWdlIjoyLCJzaXplIjoyMH0",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyLCJzaXplIjoyMH0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.id`string
- `data.items`array
- `data.items[].ad`integer
- `data.items[].ads`integer
- `data.items[].ai_video`integer
- `data.items[].content_type`string
- `data.items[].create_time`string
- `data.items[].description`string
- `data.items[].duration`string
- `data.items[].id`string
- `data.items[].original_duration`number
- `data.items[].revenue`string
- `data.items[].sale`string
- `data.items[].views`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [The videos on the product page (first page only)](https://tokconnect.com/docs/api/products/#get-products-id-videos)

`GET /v1/products/{id}/videos`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Product id (`products[].id`) or a TikTok Shop product link.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `product` tool with `method: videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "product",
  "arguments": {
    "method": "videos",
    "id": "1731896769144001226"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/products/1731896769144001226/videos" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/products/1731896769144001226/videos", {
  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:

```json
{
  "data": {
    "hasMore": false,
    "page": "product_videos",
    "source": "pdp",
    "videos": [
      {
        "caption": "The definition of a high shine gloss!😍🤏🏽🫦#trulylipgloss #trulybeauty #tiktokshopstockup #tiktokshopcreatorpicks #tiktokshopmothersday",
        "creatorId": "7384276485555094570",
        "creatorName": "Peta🎀",
        "durationSec": 32.2,
        "earnsCommission": true,
        "likes": 72013,
        "posted": "2026-04-30T04:39:25Z",
        "videoId": "7634407159618489630",
        "views": 6015574
      },
      {
        "caption": "shade: soft serve 🎀🍦 extra hydration with hyaluronic acid! 💦 @Truly Beauty #hyaluronicacid #lipgloss #lipcare #lipessentials #lippies",
        "creatorId": "6807303228855305221",
        "creatorName": "leah ♡",
        "durationSec": 16.973,
        "earnsCommission": true,
        "likes": 66363,
        "posted": "2025-12-14T08:40:54Z",
        "videoId": "7583630601534672158",
        "views": 2922982
      },
      {
        "caption": "Trulys LIP GLOSS 💋✨ I need every single shade #tiktokshopcreatorpicks #tiktokshopmemorialday #ttsverticalpro #trulybeauty #lipgloss @Truly Beauty",
        "creatorId": "6813360351690949637",
        "creatorName": "ChavonSade🦋",
        "durationSec": 18.134,
        "earnsCommission": true,
        "likes": 69809,
        "posted": "2026-05-11T17:30:44Z",
        "videoId": "7638687816909671694",
        "views": 5151748
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.page`string
- `data.source`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].creatorId`string
- `data.videos[].creatorName`string
- `data.videos[].durationSec`number
- `data.videos[].earnsCommission`boolean
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].videoId`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Browse TikTok Shop now

What a shopper sees on TikTok Shop right now: search results, keyword and category pages, deals and flash sales. Returns price, discount, displayed units sold, rating and shop. Displayed sold counts are lifetime and broad single-word searches can return only a short fallback list, so this is not a sales ranking: use [Rankings](https://tokconnect.com/docs/api/rankings/) for best sellers.

Search, keyword-page and category-page take region. Deals, flash sales and the other Shop pages read the US store.

### [A category page (category_id + slug)](https://tokconnect.com/docs/api/products/#get-storefront-category-page)

`GET /v1/storefront/category-page`

1 credit per call · 17 markets

#### Parameters

- `category_id` (string): Category id from relatedCategories.

**1 more optional parameter**

- `slug` (string): Optional category slug from `relatedCategories[].slug` on a keyword page, for example lip-treatments.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop_browse` tool with `method: category_page`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop_browse",
  "arguments": {
    "method": "category_page",
    "category_id": "601450"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/storefront/category-page?category_id=601450" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  category_id: "601450",
});
const res = await fetch(`https://api.tokconnect.com/v1/storefront/category-page?${params}`, {
  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:

```json
{
  "data": {
    "category": {
      "id": "601450",
      "name": "Beauty & Personal Care",
      "slug": "c"
    },
    "component_names": [
      "user_info",
      "page_header",
      "bread_crumbs"
    ],
    "hasMore": true,
    "page": "category",
    "products": [
      {
        "brand": "Gurunanda",
        "currency": "USD",
        "id": "1729388303591248135",
        "price": 19.49,
        "rating": 4.4,
        "reviews": 97948,
        "sellerId": "7495134783373216007",
        "shop": "GuruNanda LLC",
        "sold": 1536366,
        "title": "GuruNanda Whitening Strips, 7-day treatment (7 Packets - 2 Strips per pack) - Non-Slip, Dry Strip Technology",
        "url": "https://shop.tiktok.com/us/pdp/whitening-strips-by-gurunanda-for-sensitive-teeth-7-day-treatment-kit/1729388303591248135"
      },
      {
        "brand": "Mad Rabbit",
        "currency": "USD",
        "id": "1729386349123571788",
        "price": 26,
        "rating": 4.5,
        "reviews": 1145,
        "sellerId": "7495157675807574092",
        "shop": "Mad Rabbit",
        "sold": 9929,
        "title": "Mad Rabbit Tattoo Balm & Aftercare Cream- Color Enhancement that Revives Old Tattoos, Hydrates New Tattoos, Made With Clean Ingredients + Petroleum Free, Daily Tattoo Lotion Moisturizer & Brightener",
        "url": "https://shop.tiktok.com/us/pdp/tattoo-balm-by-mad-rabbit-clean-vegan-aftercare-for-new-old-tattoos/1729386349123571788"
      },
      {
        "brand": "tarte",
        "currency": "USD",
        "discount": "50%",
        "id": "1729417067781002172",
        "originalPrice": 93.6,
        "price": 46.8,
        "rating": 4.5,
        "reviews": 13033,
        "sellerId": "7495150597721263036",
        "shop": "Tarte Cosmetics",
        "sold": 228876,
        "title": "tarte sculpt tape & blush tape duo - blush and bronzer",
        "url": "https://shop.tiktok.com/us/pdp/sculpt-tape-blush-tape-duo-by-tarte-cosmetics-for-defined-cheeks/1729417067781002172"
      }
    ],
    "source": "https://shop.tiktok.com/us/c/c/601450"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.category`object
- `data.category.id`string
- `data.category.name`string
- `data.category.slug`string
- `data.component_names`array
- `data.hasMore`boolean
- `data.page`string
- `data.products`array
- `data.products[].brand`string
- `data.products[].currency`string
- `data.products[].id`string
- `data.products[].price`number
- `data.products[].rating`number
- `data.products[].reviews`integer
- `data.products[].sellerId`string
- `data.products[].shop`string
- `data.products[].sold`integer
- `data.products[].title`string
- `data.products[].url`string
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [The deals feed](https://tokconnect.com/docs/api/products/#get-storefront-deals)

`GET /v1/storefront/deals`

1 credit per call

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/products/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop_browse` tool with `method: deals`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop_browse",
  "arguments": {
    "method": "deals"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/storefront/deals" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/storefront/deals", {
  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:

```json
{
  "data": {
    "component_names": [
      "user_info",
      "page_header",
      "bread_crumbs"
    ],
    "hasMore": true,
    "next": "eyJjdXJzb3IiOjQxfQ",
    "page": "deals",
    "path": "deals/recommended-for-you",
    "products": [
      {
        "brand": "ZUY",
        "currency": "USD",
        "discount": "33%",
        "id": "1732013337089577703",
        "originalPrice": 35.99,
        "price": 23.99,
        "rating": 4.7,
        "reviews": 5520,
        "sellerId": "7496301427006606055",
        "shop": "ZUY US",
        "sold": 42272,
        "title": "Unisex Zip Up Jackets Vintage Washed Coat Streetwear Hoodies Unisex Soft Material Casual Fashion Essential Tops for Men Day Womenswear",
        "url": "https://shop.tiktok.com/us/pdp/vintage-washed-zip-up-jacket-unisex-soft-material-casual-style/1732013337089577703"
      },
      {
        "brand": "Whyte",
        "currency": "USD",
        "discount": "51%",
        "id": "1731573006366183970",
        "originalPrice": 42.99,
        "price": 20.88,
        "rating": 3.6,
        "reviews": 855,
        "sellerId": "7495999835031243298",
        "shop": "WHYTE",
        "sold": 20445,
        "title": "Whyte Purple Teeth Whitening Powder, Nano Hydroxyapate, PAP+, Xylitol. Sulfate Free Formula - Mint Flavor",
        "url": "https://shop.tiktok.com/us/pdp/purple-teeth-whitening-powder-brighter-smile-today/1731573006366183970"
      },
      {
        "brand": "TIRTIR",
        "currency": "USD",
        "discount": "27%",
        "id": "1732154203314098778",
        "originalPrice": 30,
        "price": 21.83,
        "rating": 4.6,
        "reviews": 1887,
        "sellerId": "7495857443730262618",
        "shop": "TIRTIR Inc.",
        "sold": 16270,
        "title": "[TIRTIR Official] Seal the Deal Long-Wear Makeup Finishing Mist Setㅣ Mask Fit Waterproof Setting Spray 80ml & Mask Fit Makeup Fixer 80ml",
        "url": "https://shop.tiktok.com/us/pdp/tirtir-official-long-wear-makeup-finishing-mist-set-80ml/1732154203314098778"
      }
    ],
    "source": "https://shop.tiktok.com/us/deals/recommended-for-you"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOjQxfQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.component_names`array
- `data.hasMore`boolean
- `data.next`string
- `data.page`string
- `data.path`string
- `data.products`array
- `data.products[].brand`string
- `data.products[].currency`string
- `data.products[].discount`string
- `data.products[].id`string
- `data.products[].originalPrice`number
- `data.products[].price`number
- `data.products[].rating`number
- `data.products[].reviews`integer
- `data.products[].sellerId`string
- `data.products[].shop`string
- `data.products[].sold`integer
- `data.products[].title`string
- `data.products[].url`string
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Flash sales](https://tokconnect.com/docs/api/products/#get-storefront-flash-sales)

`GET /v1/storefront/flash-sales`

1 credit per call

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/products/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop_browse` tool with `method: flash_sales`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop_browse",
  "arguments": {
    "method": "flash_sales"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/storefront/flash-sales" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/storefront/flash-sales", {
  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:

```json
{
  "data": {
    "component_names": [
      "user_info",
      "page_header",
      "bread_crumbs"
    ],
    "hasMore": true,
    "next": "eyJleGNsdWRlX3Byb2R1Y3RfaWRzIjpbIjE3MzI1Mzg2OTk2ODMwNDEzMTUiLCIxNzMyNTY2NTY1MDA3ODIzNjIyIiwiMTczMTc0MjU5OTU4NDE5MDg4NSIsIjE3MzIyNDQyODk3MDU5MDY3NTEiLCIxNzMxOTc3OTgwNzkzOTUwODE1IiwiMTcyOTc2ODYxMDIxMDA5MTc3MiIsIjE3MzE2NzYzMTU2MDYyOTA4NDkiLCI…",
    "page": "flash_sales",
    "path": "deals/flash-sales",
    "products": [
      {
        "brand": "Aoqta",
        "currency": "USD",
        "discount": "37%",
        "id": "1732538699683041315",
        "originalPrice": 29.96,
        "price": 19.01,
        "rating": 4.6,
        "reviews": 20,
        "sellerId": "7496222237926983715",
        "shop": "Aoqta",
        "sold": 239,
        "title": "Aoqta Women’s 2-Piece Yoga Athletic Sportswear Set - Square Neck Long Sleeve Top, High Waist Butt Lifting Flared Pants, Machine Washable Workout Sets Women for Gym,sohochic",
        "url": "https://shop.tiktok.com/us/pdp/aoqta-womens-2-piece-quick-dry-gym-set-yoga-dance-wear/1732538699683041315"
      },
      {
        "brand": "MAGIC JOHN",
        "currency": "USD",
        "discount": "50%",
        "id": "1732566565007823622",
        "originalPrice": 11.96,
        "price": 5.98,
        "rating": 4.5,
        "reviews": 234,
        "sellerId": "7495468182119418630",
        "shop": "MAGIC JOHN",
        "sold": 5545,
        "title": "MAGIC JOHN MagicView Ultra-Slim Scratch Resistant Privacy/HD Glass Screen Protector for iPhone 18/17/16/15 Series, 2-Pack Phone Accessories, 0.33mm, No Black Border, Auto Dust Removal, Easy Installation, Case-Friendly, Anti-Peek Privacy…",
        "url": "https://shop.tiktok.com/us/pdp/magic-john-screen-protector-for-iphone-17-16-15-2-pack-0-33mm/1732566565007823622"
      },
      {
        "brand": "YCZ",
        "currency": "USD",
        "discount": "50%",
        "id": "1731742599584190885",
        "originalPrice": 53.88,
        "price": 26.99,
        "rating": 4.7,
        "reviews": 1230,
        "sellerId": "7495623134499408293",
        "shop": "Y CZ",
        "sold": 8155,
        "title": "[YCZ] Men's Midnight Marine EDP Cologne, 2×50mL/1.7oz Aquatic Marine & Citrus Woody Perfume for Adults, Captivating Scent, Long-Lasting Luxurious Fragrance for Dates & Summer Use,familyfun",
        "url": "https://shop.tiktok.com/us/pdp/2-pack-unisex-eau-de-parfum-100ml-ocean-fresh-scent/1731742599584190885"
      }
    ],
    "source": "https://shop.tiktok.com/us/deals/flash-sales"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJleGNsdWRlX3Byb2R1Y3RfaWRzIjpbIjE3MzI1Mzg2OTk2ODMwNDEzMTUiLCIxNzMyNTY2NTY1MDA3ODIzNjIyIiwiMTczMTc0MjU5OTU4NDE5MDg4NSIsIjE3MzIyNDQyODk3MDU5MDY3NTEiLCIxNzMxOTc3OTgwNzkzOTUwODE1IiwiMTcyOTc2ODYxMDIxMDA5MTc3MiIsIjE3MzE2NzYzMTU2MDYyOTA4NDkiLCI…"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.component_names`array
- `data.hasMore`boolean
- `data.next`string
- `data.page`string
- `data.path`string
- `data.products`array
- `data.products[].brand`string
- `data.products[].currency`string
- `data.products[].discount`string
- `data.products[].id`string
- `data.products[].originalPrice`number
- `data.products[].price`number
- `data.products[].rating`number
- `data.products[].reviews`integer
- `data.products[].sellerId`string
- `data.products[].shop`string
- `data.products[].sold`integer
- `data.products[].title`string
- `data.products[].url`string
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [An SEO keyword page (slug)](https://tokconnect.com/docs/api/products/#get-storefront-keyword-page)

`GET /v1/storefront/keyword-page`

1 credit per call · 17 markets

#### Parameters

- `slug` (string): Keyword slug from `relatedSearches[].slug` on a keyword page, for example lip-oil.

**1 more optional parameter**

- `filters` (array of string): TikTok filter ids from a previous response's filters, e.g. `ecom_rating_stat`|RATING_4.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop_browse` tool with `method: keyword_page`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop_browse",
  "arguments": {
    "method": "keyword_page",
    "slug": "lip-oil"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/storefront/keyword-page?slug=lip-oil" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/storefront/keyword-page",
    params={
        "slug": "lip-oil",
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  slug: "lip-oil",
});
const res = await fetch(`https://api.tokconnect.com/v1/storefront/keyword-page?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJvZmZzZXQiOjMwfQ",
    "page": "keyword",
    "products": [
      {
        "currency": "USD",
        "discount": "53%",
        "id": "1729500724221286212",
        "originalPrice": 14.99,
        "price": 6.99,
        "rating": 4.7,
        "reviews": 490,
        "sellerId": "7496260439930211140",
        "shop": "PureGlam Lab",
        "sold": 2044,
        "title": "Women's 2-Pcs Natural Lip Care Gift Set - Moisturizing Balm, Lip Oil, Glossy Lipgloss, Gentle Conditioner, Bottle Packaging | Daily Softening | Back-to-School Gift for Personal Use",
        "url": "https://shop.tiktok.com/us/pdp/2-piece-3-in-1-lip-care-set-hydrating-lip-balm-gloss/1729500724221286212"
      },
      {
        "brand": "NOONI",
        "currency": "USD",
        "id": "1729440860171702516",
        "price": 15,
        "rating": 4.3,
        "reviews": 35969,
        "sellerId": "7495586169586223348",
        "shop": "NOONI",
        "sold": 346768,
        "title": "Nooni Korean Apple Lip Oil + Lip Stain | Glossy Lip Stain, Tinting & Long Lasting, Moisturizing Lip Care (17 options) Hydrate Lipgloss Lipstick Makeup Glossy Hydrating Moisturizer Plump Transfer-proof",
        "url": "https://shop.tiktok.com/us/pdp/apple-lip-oil-by-nooni-moisturizing-tint-softening-care-3-7ml/1729440860171702516"
      },
      {
        "currency": "USD",
        "discount": "38%",
        "id": "1732388535932916327",
        "originalPrice": 20.99,
        "price": 12.99,
        "rating": 4.8,
        "reviews": 32,
        "sellerId": "7494591973747295847",
        "shop": "Kore Mart US",
        "sold": 119,
        "title": "[BUY 3 GET 3 FREE] 6-Count Lip Oil & Lipgloss Cosmetic Gift Set - Affordable Lip Care Treatment, Hydrates, Moisturizes, Smooths Skin, Anti-Wrinkle, Student-Friendly Beauty Item",
        "url": "https://shop.tiktok.com/us/pdp/moisturizing-clear-lip-gloss-set-6-count-student-friendly/1732388535932916327"
      }
    ],
    "relatedCategories": [
      {
        "id": "601595",
        "name": "Lip Treatments",
        "slug": "lip-treatments"
      },
      {
        "id": "601534",
        "name": "Lipstick & Lip Gloss",
        "slug": "lipstick-lip-gloss"
      },
      {
        "id": "601529",
        "name": "Makeup Sets",
        "slug": "makeup-sets"
      }
    ],
    "relatedSearches": [
      {
        "name": "Lip Therapy",
        "slug": "lip-therapy"
      },
      {
        "name": "oil lipstick",
        "slug": "oil-lipstick"
      },
      {
        "name": "Lip lingerie",
        "slug": "lip-lingerie"
      }
    ],
    "shops": [
      {
        "name": "NOONI",
        "sellerId": "7495586169586223348"
      },
      {
        "name": "e.l.f. Cosmetics",
        "sellerId": "7494913857786775843"
      },
      {
        "name": "COVERGIRL",
        "sellerId": "7496133101336103678"
      }
    ],
    "source": "https://shop.tiktok.com/us/k/lip-oil"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjMwfQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.page`string
- `data.products`array
- `data.products[].currency`string
- `data.products[].discount`string
- `data.products[].id`string
- `data.products[].originalPrice`number
- `data.products[].price`number
- `data.products[].rating`number
- `data.products[].reviews`integer
- `data.products[].sellerId`string
- `data.products[].shop`string
- `data.products[].sold`integer
- `data.products[].title`string
- `data.products[].url`string
- `data.relatedCategories`array
- `data.relatedCategories[].id`string
- `data.relatedCategories[].name`string
- `data.relatedCategories[].slug`string
- `data.relatedSearches`array
- `data.relatedSearches[].name`string
- `data.relatedSearches[].slug`string
- `data.shops`array
- `data.shops[].name`string
- `data.shops[].sellerId`string
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Any other Shop page by path](https://tokconnect.com/docs/api/products/#get-storefront-page)

`GET /v1/storefront/page`

1 credit per call

#### Parameters

- `path` (string): Any other Shop path, e.g. store/`{slug}`/`{seller_id}` or deals/premium-offers.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop_browse` tool with `method: path`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop_browse",
  "arguments": {
    "method": "path"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/storefront/page" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/storefront/page", {
  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:

```json
{
  "data": {
    "component_names": [
      "user_info",
      "page_header",
      "campaign_hero_banner"
    ],
    "hasMore": false,
    "page": "mall",
    "path": "",
    "products": [
      {
        "brand": "Leefar",
        "currency": "USD",
        "discount": "63%",
        "id": "1730743411790877344",
        "originalPrice": 34.87,
        "price": 12.89,
        "rating": 4.7,
        "reviews": 2507,
        "sellerId": "7495951453623650976",
        "shop": "Leefar Supplements",
        "sold": 24092,
        "title": "LeeFar Her Juicy Feminine Probiotics Gummies- All in One Solution with Slippery Elm and Prebiotics&Lactobacillus Probiotic Blend for Women's pH Balance and Dryness - Hawaiian Pineapple Gummies 60 Counts",
        "url": "https://shop.tiktok.com/us/pdp/womens-probiotic-gummies-by-leefar-60-count-with-prebiotics-slippery-elm/1730743411790877344"
      },
      {
        "brand": "YOULUCK",
        "currency": "USD",
        "discount": "56%",
        "id": "1730661941307937028",
        "originalPrice": 30.9,
        "price": 13.6,
        "rating": 4.7,
        "reviews": 1700,
        "sellerId": "7495486250805332228",
        "shop": "YouLuck Beauty",
        "sold": 30021,
        "title": "YOULUCK Velvet Touch Cluster Lashes Kit - 3D False Eyelashes & Adhesives, Waterproof Dramatic Eyelash Extensions, Ultra-Thin Band, Bond, Seal, Remover, Tweezer, Beginner-Friendly Beauty Cosmetic for Girls,familyfun",
        "url": "https://shop.tiktok.com/us/pdp/youluck-lash-clusters-waterproof-long-lasting-beginner-friendly/1730661941307937028"
      },
      {
        "brand": "Pigeon",
        "currency": "USD",
        "discount": "37%",
        "id": "1732157479503172113",
        "originalPrice": 40.99,
        "price": 25.69,
        "rating": 4.8,
        "reviews": 107,
        "sellerId": "7496091900942912017",
        "shop": "Pigeon USA",
        "sold": 2574,
        "title": "Pigeon Glass Nursing Baby Bottle (Pack of 2) Wide Neck, Anti-Colic, Streamlined Body, Natural Feel, Easy to Clean, (0m+) baby registry essential Heat-Resistant, 5.4 Oz, Includes 2pcs SS Nipples",
        "url": "https://shop.tiktok.com/us/pdp/pigeon-glass-nursing-baby-bottle-pack-of-2-anti-colic-5-4-oz/1732157479503172113"
      }
    ],
    "source": "https://shop.tiktok.com/us"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.component_names`array
- `data.hasMore`boolean
- `data.page`string
- `data.path`string
- `data.products`array
- `data.products[].brand`string
- `data.products[].currency`string
- `data.products[].discount`string
- `data.products[].id`string
- `data.products[].originalPrice`number
- `data.products[].price`number
- `data.products[].rating`number
- `data.products[].reviews`integer
- `data.products[].sellerId`string
- `data.products[].shop`string
- `data.products[].sold`integer
- `data.products[].title`string
- `data.products[].url`string
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Shop search results](https://tokconnect.com/docs/api/products/#get-storefront-search)

`GET /v1/storefront/search`

1 credit per call · 17 markets

#### Parameters

- `keyword` (string): Product search phrase.

**2 more optional parameters**

- `filters` (array of string): TikTok filter ids from a previous response's filters, e.g. `ecom_rating_stat`|RATING_4.
- `sort` (string): `best_sellers`, newest, `price_desc` or `price_asc` (default relevance). The result's sortApplied says whether TikTok sorted the results (tiktok) or only this page was sorted (page). **One of** `best_sellers` `newest` `price_desc` `price_asc`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop_browse` tool with `method: search`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop_browse",
  "arguments": {
    "method": "search",
    "keyword": "lip oil"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/storefront/search?keyword=lip%20oil" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
});
const res = await fetch(`https://api.tokconnect.com/v1/storefront/search?${params}`, {
  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:

```json
{
  "data": {
    "filters": [
      {
        "group": "Sort by",
        "options": [
          {
            "id": "ecom_sold_count",
            "name": "Best sellers"
          },
          {
            "id": "ecom_publish_time",
            "name": "Newest"
          }
        ]
      },
      {
        "group": "Promotions",
        "options": [
          {
            "id": "ecom_promotion_tag_stat",
            "name": "Deals"
          },
          {
            "id": "ecom_free_shipping_stat",
            "name": "Free Shipping"
          }
        ]
      }
    ],
    "hasMore": true,
    "next": "eyJvZmZzZXQiOjMwLCJwYWdlX3Rva2VuIjoiMjAyNjEwMzAyMzI5MjRGQjc0MTlBODFDQjk5MzE4M0U4MiJ9",
    "page": "search",
    "products": [
      {
        "brand": "NOONI",
        "currency": "USD",
        "id": "1729440860171702516",
        "price": 15,
        "rating": 4.3,
        "reviews": 35969,
        "sellerId": "7495586169586223348",
        "shop": "NOONI",
        "sold": 346768,
        "title": "Nooni Korean Apple Lip Oil + Lip Stain | Glossy Lip Stain, Tinting & Long Lasting, Moisturizing Lip Care (17 options) Hydrate Lipgloss Lipstick Makeup Glossy Hydrating Moisturizer Plump Transfer-proof",
        "url": "https://shop.tiktok.com/us/pdp/apple-lip-oil-by-nooni-moisturizing-tint-softening-care-3-7ml/1729440860171702516"
      },
      {
        "brand": "e.l.f.",
        "currency": "USD",
        "id": "1729407202568147235",
        "price": 13,
        "rating": 4.8,
        "reviews": 18626,
        "sellerId": "7494913857786775843",
        "shop": "e.l.f. Cosmetics",
        "sold": 228428,
        "title": "e.l.f. Glow Reviver Lip Oil, Nourishing Lip Oil High-Gloss Finish 0.25 oz (7.6 mL)",
        "url": "https://shop.tiktok.com/us/pdp/glow-reviver-lip-oil-by-e-l-f-cosmetics-hydrating-tinted-formula/1729407202568147235"
      }
    ],
    "relatedCategories": [
      {
        "id": "601534",
        "name": "Lipstick & Lip Gloss",
        "slug": "lipstick-lip-gloss"
      },
      {
        "id": "601595",
        "name": "Lip Treatments",
        "slug": "lip-treatments"
      }
    ],
    "relatedSearches": [
      {
        "name": "lip oils",
        "slug": "lip-oils"
      },
      {
        "name": "lip oil vs lip gloss",
        "slug": "lip-oil-vs-lip-gloss"
      }
    ],
    "shops": [
      {
        "name": "NOONI",
        "sellerId": "7495586169586223348"
      },
      {
        "name": "e.l.f. Cosmetics",
        "sellerId": "7494913857786775843"
      }
    ],
    "source": "https://shop.tiktok.com/us/s"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjMwLCJwYWdlX3Rva2VuIjoiMjAyNjEwMzAyMzI5MjRGQjc0MTlBODFDQjk5MzE4M0U4MiJ9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.filters`array
- `data.filters[].group`string
- `data.filters[].options`array
- `data.filters[].options[].id`string
- `data.filters[].options[].name`string
- `data.hasMore`boolean
- `data.next`string
- `data.page`string
- `data.products`array
- `data.products[].brand`string
- `data.products[].currency`string
- `data.products[].id`string
- `data.products[].price`integer
- `data.products[].rating`number
- `data.products[].reviews`integer
- `data.products[].sellerId`string
- `data.products[].shop`string
- `data.products[].sold`integer
- `data.products[].title`string
- `data.products[].url`string
- `data.relatedCategories`array
- `data.relatedCategories[].id`string
- `data.relatedCategories[].name`string
- `data.relatedCategories[].slug`string
- `data.relatedSearches`array
- `data.relatedSearches[].name`string
- `data.relatedSearches[].slug`string
- `data.shops`array
- `data.shops[].name`string
- `data.shops[].sellerId`string
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/products/

---

# TikTok Shop seller API

One TikTok Shop seller: its storefront, sales split by channel, daily trend, products, launches, affiliates and the videos that sell for it.

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

Call these routes with your own key, or ask the same question in plain words.

[Get an API key](https://app.tokconnect.com/api-key)[Ask about a seller](https://app.tokconnect.com/?q=Which%20shops%20launched%20the%20most%20new%20products%20last%20month%20on%20TikTok%20Shop%20US%3F)[Try it free in Shop Analytics](https://tokconnect.com/tools/tiktok-shop-analytics/)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/shops/{id}`](https://tokconnect.com/docs/api/shops/#get-shops-id) | Live storefront: rating, sold, followers, products |
| [GET `/v1/shops/{id}/sales`](https://tokconnect.com/docs/api/shops/#get-shops-id-sales) | Revenue and units, split by own accounts, affiliates and mall |
| [GET `/v1/shops/{id}/trend`](https://tokconnect.com/docs/api/shops/#get-shops-id-trend) | Daily revenue and units (up to ~13 months) |
| [GET `/v1/shops/{id}/products`](https://tokconnect.com/docs/api/shops/#get-shops-id-products) | Its products ranked by revenue |
| [GET `/v1/shops/{id}/new-products`](https://tokconnect.com/docs/api/shops/#get-shops-id-new-products) | Products it launched in the window |
| [GET `/v1/shops/{id}/strategy`](https://tokconnect.com/docs/api/shops/#get-shops-id-strategy) | Price bands and sales-channel mix |
| [GET `/v1/shops/{id}/creators`](https://tokconnect.com/docs/api/shops/#get-shops-id-creators) | Affiliate creators selling for it, with revenue |
| [GET `/v1/shops/{id}/new-affiliates`](https://tokconnect.com/docs/api/shops/#get-shops-id-new-affiliates) | Daily count of new affiliates who started promoting the shop, with a summary |
| [GET `/v1/shops/{id}/affiliate-videos`](https://tokconnect.com/docs/api/shops/#get-shops-id-affiliate-videos) | Daily count of new videos affiliates posted for the shop, with a summary |
| [GET `/v1/shops/{id}/videos`](https://tokconnect.com/docs/api/shops/#get-shops-id-videos) | Videos selling its products, with revenue |

## Common parameters

These read the same on the routes below that take them.

- `region` (string): Market as an ISO country code, default US. Amounts are in the market's currency. See [Markets](https://tokconnect.com/docs/api/markets/).
- `window` (string): Date range ending at the last complete day (about 2 days ago). Default 30d. Use start and end for a custom range. **One of** `7d` `30d` `90d` `180d` `365d`.
- `start` (string): Custom range start, YYYY-MM-DD.
- `end` (string): Custom range end, YYYY-MM-DD (capped at the last complete day).
- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## One TikTok Shop seller

Everything about one TikTok Shop seller (id = sellerId). Find the id on any product, or from [`GET /v1/shops/top`](https://tokconnect.com/docs/api/rankings/#get-shops-top) with the shop name. Then call:

- **Live storefront**: store (what shoppers see: rating, followers, catalogue).
- **Sales and trend** (Shop Analytics, any market via region): sales (own, affiliate and mall revenue), trend (daily).
- **Products and launches**: products, new products, strategy (pricing, top affiliates unnamed).
- **Affiliates and videos**: creators, videos, new affiliates and affiliate videos (daily counts with summary).

Revenue and units are estimates: units follow TikTok's sold counter and revenue is units times the listed price.

### [Live storefront: rating, sold, followers, products](https://tokconnect.com/docs/api/shops/#get-shops-id)

`GET /v1/shops/{id}`

1 credit per call · 17 markets

#### Parameters

- `id` (string, path, required): Seller id (sellerId on products and stores).

**1 more optional parameter**

- `slug` (string): Store slug if known; looked up when omitted.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop` tool with `method: store`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop",
  "arguments": {
    "method": "store",
    "id": "7495153913553128138"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/7495153913553128138" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/shops/7495153913553128138", {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJzZWFyY2hfcGFyYW1zIjoiMjBfV3prMU16TXNOall3TURBd01EQXNNVGMxTlRFeU1EVXdPRGMxTml3aU1UY3pNVFl4TWpVNU5UVTVOekU0TlRjek9DSmQifQ",
    "page": "store",
    "products": [
      {
        "brand": "Truly Beauty",
        "currency": "USD",
        "id": "1729430515554816714",
        "price": 18,
        "rating": 4.2,
        "reviews": 25004,
        "sellerId": "7495153913553128138",
        "shop": "Truly Beauty",
        "sold": 219142,
        "title": "Unicorn Fruit Brightening and Smoothing Deodorant – Aluminum-Free, Fights Odor-Causing Bacteria with Papaya Enzymes & Mango Butter – Helps Fade Dark Underarm Discoloration – Removes Impurities & Dead Skin – Sweet Cotton Candy Scent",
        "url": "https://shop.tiktok.com/us/pdp/deodorant-truly-beauty-unicorn-fruit-cotton-candy-scent-for-bright-skin/1729430515554816714"
      },
      {
        "brand": "Truly Beauty",
        "currency": "USD",
        "discount": "52%",
        "id": "1731896769144001226",
        "originalPrice": 29,
        "price": 13.92,
        "rating": 4.5,
        "reviews": 14795,
        "sellerId": "7495153913553128138",
        "shop": "Truly Beauty",
        "sold": 153731,
        "title": "Hydrating Lip Gloss - High Shine & Tinted, Infused with Hyaluronic Acid, Jojoba Oil & Shea Butter",
        "url": "https://shop.tiktok.com/us/pdp/hydrating-lip-gloss-high-shine-tinted-hyaluronic-acid/1731896769144001226"
      },
      {
        "brand": "Truly Beauty",
        "currency": "USD",
        "id": "1729445990437982922",
        "price": 33,
        "rating": 4.5,
        "reviews": 16603,
        "sellerId": "7495153913553128138",
        "shop": "Truly Beauty",
        "sold": 150492,
        "title": "Soft Serve After Shave Oil – Soothes Razor Burn and Redness with Peptides & Hyaluronic Acid – Increases Collagen Production – Prevents Ingrowns and Brightens Uneven Skin Tone for Smoother Legs, Underarms & Pubic Area – Strawberry Vanilla…",
        "url": "https://shop.tiktok.com/us/pdp/after-shave-oil-by-truly-beauty-soft-serve-strawberry-vanilla-scent/1729445990437982922"
      }
    ],
    "shop": {
      "name": "Truly Beauty",
      "sellerId": "7495153913553128138"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJzZWFyY2hfcGFyYW1zIjoiMjBfV3prMU16TXNOall3TURBd01EQXNNVGMxTlRFeU1EVXdPRGMxTml3aU1UY3pNVFl4TWpVNU5UVTVOekU0TlRjek9DSmQifQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.page`string
- `data.products`array
- `data.products[].brand`string
- `data.products[].currency`string
- `data.products[].id`string
- `data.products[].price`integer
- `data.products[].rating`number
- `data.products[].reviews`integer
- `data.products[].sellerId`string
- `data.products[].shop`string
- `data.products[].sold`integer
- `data.products[].title`string
- `data.products[].url`string
- `data.shop`object
- `data.shop.name`string
- `data.shop.sellerId`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Revenue and units, split by own accounts, affiliates and mall](https://tokconnect.com/docs/api/shops/#get-shops-id-sales)

`GET /v1/shops/{id}/sales`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Seller id (sellerId on products and stores).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop` tool with `method: sales`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop",
  "arguments": {
    "method": "sales",
    "id": "7495153913553128138"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/7495153913553128138/sales" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/shops/7495153913553128138/sales", {
  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:

```json
{
  "data": {
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "7495153913553128138",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totals": {
      "affiliate_percentage": 99.48,
      "affiliate_revenue": "$1.88m",
      "day_affiliate_revenue": "$62.53k",
      "day_other_revenue": "$323.10",
      "day_revenue": "$62.86k",
      "day_sale": "3.51k",
      "day_self_promotion_revenue": "$4.96",
      "day_shopping_mall_revenue": "$323.10",
      "live_revenue": "$487.09k",
      "original_affiliate_revenue": 1875836.63,
      "original_live_revenue": 487085.31,
      "original_revenue": 1885678.59,
      "original_self_promotion_revenue": 148.95,
      "original_shopping_mall_revenue": 9693.01,
      "original_showcase_revenue": 9693.01,
      "original_video_revenue": 1388900.27,
      "other_percentage": 0.51,
      "other_revenue": "$9.69k",
      "revenue": "$1.89m",
      "sale": "105.23k",
      "self_promotion_percentage": 0.01,
      "self_promotion_revenue": "$148.95",
      "shopping_mall_percentage": 0.51,
      "shopping_mall_revenue": "$9.69k",
      "showcase_revenue": "$9.69k",
      "unit_price": "$17.92",
      "video_revenue": "$1.39m"
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.totals`object
- `data.totals.affiliate_percentage`number
- `data.totals.affiliate_revenue`string
- `data.totals.day_affiliate_revenue`string
- `data.totals.day_other_revenue`string
- `data.totals.day_revenue`string
- `data.totals.day_sale`string
- `data.totals.day_self_promotion_revenue`string
- `data.totals.day_shopping_mall_revenue`string
- `data.totals.live_revenue`string
- `data.totals.original_affiliate_revenue`number
- `data.totals.original_live_revenue`number
- `data.totals.original_revenue`number
- `data.totals.original_self_promotion_revenue`number
- `data.totals.original_shopping_mall_revenue`number
- `data.totals.original_showcase_revenue`number
- `data.totals.original_video_revenue`number
- `data.totals.other_percentage`number
- `data.totals.other_revenue`string
- `data.totals.revenue`string
- `data.totals.sale`string
- `data.totals.self_promotion_percentage`number
- `data.totals.self_promotion_revenue`string
- `data.totals.shopping_mall_percentage`number
- `data.totals.shopping_mall_revenue`string
- `data.totals.showcase_revenue`string
- `data.totals.unit_price`string
- `data.totals.video_revenue`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Daily revenue and units (up to ~13 months)](https://tokconnect.com/docs/api/shops/#get-shops-id-trend)

`GET /v1/shops/{id}/trend`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Seller id (sellerId on products and stores).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop` tool with `method: trend`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop",
  "arguments": {
    "method": "trend",
    "id": "7495153913553128138"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/7495153913553128138/trend" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/shops/7495153913553128138/trend", {
  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:

```json
{
  "data": {
    "coverage": {
      "days": 30,
      "daysWithSales": 30,
      "firstDayWithSales": "2026-09-29"
    },
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "7495153913553128138",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "series": [
      {
        "affiliate_revenue": 57675.27,
        "partition_day": "2026-09-29",
        "revenue": 58261.27,
        "sale": 2582,
        "self_promotion_revenue": 0,
        "shopping_mall_revenue": 586,
        "unit_price": 22.56
      },
      {
        "affiliate_revenue": 1843,
        "partition_day": "2026-09-30",
        "revenue": 1843,
        "sale": 56,
        "self_promotion_revenue": 0,
        "shopping_mall_revenue": 0,
        "unit_price": 32.91
      },
      {
        "affiliate_revenue": 1506,
        "partition_day": "2026-10-01",
        "revenue": 1506,
        "sale": 46,
        "self_promotion_revenue": 0,
        "shopping_mall_revenue": 0,
        "unit_price": 32.74
      }
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totals": {
      "revenue": 1885679,
      "units": 105234
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.coverage`object
- `data.coverage.days`integer
- `data.coverage.daysWithSales`integer
- `data.coverage.firstDayWithSales`string
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.series`array
- `data.series[].affiliate_revenue`number
- `data.series[].partition_day`string
- `data.series[].revenue`number
- `data.series[].sale`integer
- `data.series[].self_promotion_revenue`integer
- `data.series[].shopping_mall_revenue`integer
- `data.series[].unit_price`number
- `data.source`string
- `data.totals`object
- `data.totals.revenue`integer
- `data.totals.units`integer
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Its products ranked by revenue](https://tokconnect.com/docs/api/shops/#get-shops-id-products)

`GET /v1/shops/{id}/products`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Seller id (sellerId on products and stores).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop` tool with `method: products`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop",
  "arguments": {
    "method": "products",
    "id": "7495153913553128138"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/7495153913553128138/products" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/shops/7495153913553128138/products", {
  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:

```json
{
  "data": {
    "count": 20,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": true,
    "id": "7495153913553128138",
    "items": [
      {
        "collect_day": "2025-10-18",
        "id": "1731896769144001226",
        "product_title": "Hydrating Lip Gloss - High Shine & Tinted, Infused with Hyaluronic Acid, Jojoba Oil & Shea Butter",
        "revenue": "$285.28k",
        "sale": "35.66k",
        "unit_price": "$8.00"
      },
      {
        "collect_day": "2025-09-27",
        "id": "1731678264099967690",
        "product_title": "The Brightening Body Serum – Targeted Dark Spot Treatment with Vitamin C & Tranexamic Acid – Corrects Hyperpigmentation, Dark Spots & Uneven Tone – Boosts Radiance for a Brighter, Youthful-Looking Complexion – Clinical Strength Formula",
        "revenue": "$271.61k",
        "sale": "12.93k",
        "unit_price": "$21.00"
      },
      {
        "collect_day": "2024-01-13",
        "id": "1729430515554816714",
        "product_title": "Unicorn Fruit Brightening and Smoothing Deodorant – Aluminum-Free, Fights Odor-Causing Bacteria with Papaya Enzymes & Mango Butter – Helps Fade Dark Underarm Discoloration – Removes Impurities & Dead Skin – Sweet Cotton Candy Scent",
        "revenue": "$187.81k",
        "sale": "15.65k",
        "unit_price": "$12.00"
      }
    ],
    "market": "US",
    "next": "eyJwYWdlIjoyLCJzaXplIjoyMH0",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyLCJzaXplIjoyMH0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.id`string
- `data.items`array
- `data.items[].collect_day`string
- `data.items[].id`string
- `data.items[].product_title`string
- `data.items[].revenue`string
- `data.items[].sale`string
- `data.items[].unit_price`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Products it launched in the window](https://tokconnect.com/docs/api/shops/#get-shops-id-new-products)

`GET /v1/shops/{id}/new-products`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Seller id (sellerId on products and stores).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop` tool with `method: new_products`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop",
  "arguments": {
    "method": "new_products",
    "id": "7495153913553128138"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/7495153913553128138/new-products" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/shops/7495153913553128138/new-products", {
  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:

```json
{
  "data": {
    "count": 4,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": false,
    "id": "7495153913553128138",
    "items": [
      {
        "collect_day": "2026-10-20",
        "id": "1732418744492528330",
        "product_title": "Vanilla Glaze Moisturizing Body Lotion with Peptides, Ceramides, Niacinamide, Squalane & Hyaluronic Acid, 16 fl oz",
        "revenue": "$84.00",
        "sale": "3",
        "unit_price": "$28.00"
      },
      {
        "collect_day": "2026-10-21",
        "id": "1732776932999598794",
        "product_title": "Brightening Duo - All-Over Body Serum + Targeted Dark Spot Serum Set with Tranexamic Acid, Vitamin C & 4% Niacinamide – Helps Improve the Look of Dark Spots & Uneven Skin Tone",
        "revenue": "$0.00",
        "sale": "0"
      },
      {
        "collect_day": "2026-10-21",
        "id": "1732776877478941386",
        "product_title": "Hydrating Lip Gloss 2-Pack - Lip Gloss Duo Set, High Shine & Tinted, Infused with Hyaluronic Acid, Jojoba Oil & Shea Butter",
        "revenue": "$0.00",
        "sale": "0"
      }
    ],
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.id`string
- `data.items`array
- `data.items[].collect_day`string
- `data.items[].id`string
- `data.items[].product_title`string
- `data.items[].revenue`string
- `data.items[].sale`string
- `data.items[].unit_price`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Price bands and sales-channel mix](https://tokconnect.com/docs/api/shops/#get-shops-id-strategy)

`GET /v1/shops/{id}/strategy`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Seller id (sellerId on products and stores).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop` tool with `method: strategy`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop",
  "arguments": {
    "method": "strategy",
    "id": "7495153913553128138"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/7495153913553128138/strategy" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/shops/7495153913553128138/strategy", {
  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:

```json
{
  "data": {
    "affiliate": [
      {
        "creator": "Creator 1",
        "follower_count": 37000,
        "revenue": 107745
      },
      {
        "creator": "Creator 2",
        "follower_count": 15800,
        "revenue": 62205
      },
      {
        "creator": "Creator 3",
        "follower_count": 23600,
        "revenue": 58120
      }
    ],
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "7495153913553128138",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD.",
      "Individual affiliate creators are shown as Creator 1, 2, ... with their metrics. Accounts the shop owns (ownAccounts) are named."
    ],
    "ownAccounts": [
      {
        "follower_count": 3000000,
        "handle": "trulybeauty",
        "i18n_follower_count": "3m",
        "i18n_revenue": "$148.95",
        "id": "6752887346621023238",
        "live_revenue": 0,
        "nickname": "Truly Beauty",
        "revenue": 148.95,
        "sale": 5,
        "signature": "Experts in Smooth Skin ✨\nTIKTOK for 10% OFF",
        "video_revenue": 148.95
      }
    ],
    "pricing": {
      "product_count": "58",
      "product_counts": [
        222,
        222,
        222
      ],
      "product_with_sale_count": "49",
      "product_with_sale_counts": [
        44,
        2,
        3
      ],
      "revenue": "$1.89m",
      "revenues": [
        58261.27,
        1843,
        1506
      ],
      "sales": [
        2582,
        56,
        46
      ],
      "unit_price": "$17.92",
      "unit_prices": [
        22.56,
        32.91,
        32.74
      ]
    },
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.affiliate`array
- `data.affiliate[].creator`string
- `data.affiliate[].follower_count`integer
- `data.affiliate[].revenue`integer
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.ownAccounts`array
- `data.ownAccounts[].follower_count`integer
- `data.ownAccounts[].handle`string
- `data.ownAccounts[].i18n_follower_count`string
- `data.ownAccounts[].i18n_revenue`string
- `data.ownAccounts[].id`string
- `data.ownAccounts[].live_revenue`integer
- `data.ownAccounts[].nickname`string
- `data.ownAccounts[].revenue`number
- `data.ownAccounts[].sale`integer
- `data.ownAccounts[].signature`string
- `data.ownAccounts[].video_revenue`number
- `data.pricing`object
- `data.pricing.product_count`string
- `data.pricing.product_counts`array
- `data.pricing.product_with_sale_count`string
- `data.pricing.product_with_sale_counts`array
- `data.pricing.revenue`string
- `data.pricing.revenues`array
- `data.pricing.sales`array
- `data.pricing.unit_price`string
- `data.pricing.unit_prices`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Affiliate creators selling for it, with revenue](https://tokconnect.com/docs/api/shops/#get-shops-id-creators)

`GET /v1/shops/{id}/creators`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Seller id (sellerId on products and stores).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop` tool with `method: creators`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop",
  "arguments": {
    "method": "creators",
    "id": "7495153913553128138"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/7495153913553128138/creators" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/shops/7495153913553128138/creators", {
  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:

```json
{
  "data": {
    "count": 20,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": true,
    "id": "7495153913553128138",
    "items": [
      {
        "belonged_seller_id": "",
        "creatorDebut": "2025-06-14",
        "creator_type": "INDEPENDENT",
        "followers": 37000,
        "handle": "creator_1",
        "id": "7098788832553174058",
        "live_count": 0,
        "live_revenue": "$0.00",
        "nickname": "Example creator 1",
        "product_count": 7,
        "revenue": "$107.74k",
        "sale": 6040,
        "unit_price": 17.84,
        "video_count": 83,
        "video_revenue": "$107.74k"
      },
      {
        "belonged_seller_id": "",
        "creatorDebut": "2024-10-01",
        "creator_type": "INDEPENDENT",
        "followers": 15800,
        "handle": "creator_2",
        "id": "6980982804826375173",
        "live_count": 0,
        "live_revenue": "$0.00",
        "nickname": "Example creator 2",
        "product_count": 1,
        "revenue": "$62.20k",
        "sale": 1885,
        "unit_price": 33,
        "video_count": 6,
        "video_revenue": "$62.20k"
      },
      {
        "belonged_seller_id": "7495466366830020858",
        "creatorDebut": "2021-10-19",
        "creator_type": "INDEPENDENT",
        "followers": 23600,
        "handle": "creator_3",
        "id": "6790832707742417925",
        "live_count": 0,
        "live_revenue": "$0.00",
        "nickname": "Example creator 3",
        "product_count": 1,
        "revenue": "$58.12k",
        "sale": 7265,
        "unit_price": 8,
        "video_count": 176,
        "video_revenue": "$58.12k"
      }
    ],
    "market": "US",
    "next": "eyJwYWdlIjoyLCJzaXplIjoyMH0",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyLCJzaXplIjoyMH0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.id`string
- `data.items`array
- `data.items[].belonged_seller_id`string
- `data.items[].creatorDebut`string
- `data.items[].creator_type`string
- `data.items[].followers`integer
- `data.items[].handle`string
- `data.items[].id`string
- `data.items[].live_count`integer
- `data.items[].live_revenue`string
- `data.items[].nickname`string
- `data.items[].product_count`integer
- `data.items[].revenue`string
- `data.items[].sale`integer
- `data.items[].sales_volumn`integer
- `data.items[].signature`string
- `data.items[].unit_price`number
- `data.items[].video_count`integer
- `data.items[].video_revenue`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Daily count of new affiliates who started promoting the shop, with a summary](https://tokconnect.com/docs/api/shops/#get-shops-id-new-affiliates)

`GET /v1/shops/{id}/new-affiliates`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Seller id (sellerId on products and stores).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop` tool with `method: new_affiliates`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop",
  "arguments": {
    "method": "new_affiliates",
    "id": "7495153913553128138"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/7495153913553128138/new-affiliates" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/shops/7495153913553128138/new-affiliates", {
  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:

```json
{
  "data": {
    "dataEnd": "2026-10-28",
    "id": "7495153913553128138",
    "market": "US",
    "notes": [
      "Market US (United States)."
    ],
    "series": [
      {
        "day": "2026-09-29",
        "newAffiliates": 885
      },
      {
        "day": "2026-09-30",
        "newAffiliates": 1436
      },
      {
        "day": "2026-10-01",
        "newAffiliates": 1365
      }
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "summary": {
      "averagePerDay": 1255,
      "days": 30,
      "last7Days": 8881,
      "peak": {
        "day": "2026-09-30",
        "value": 1436
      },
      "previous7Days": 8474,
      "total": 37651,
      "unit": "new affiliates"
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.series`array
- `data.series[].day`string
- `data.series[].newAffiliates`integer
- `data.source`string
- `data.summary`object
- `data.summary.averagePerDay`integer
- `data.summary.days`integer
- `data.summary.last7Days`integer
- `data.summary.peak`object
- `data.summary.peak.day`string
- `data.summary.peak.value`integer
- `data.summary.previous7Days`integer
- `data.summary.total`integer
- `data.summary.unit`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Daily count of new videos affiliates posted for the shop, with a summary](https://tokconnect.com/docs/api/shops/#get-shops-id-affiliate-videos)

`GET /v1/shops/{id}/affiliate-videos`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Seller id (sellerId on products and stores).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop` tool with `method: affiliate_videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop",
  "arguments": {
    "method": "affiliate_videos",
    "id": "7495153913553128138"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/7495153913553128138/affiliate-videos" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/shops/7495153913553128138/affiliate-videos", {
  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:

```json
{
  "data": {
    "dataEnd": "2026-10-28",
    "id": "7495153913553128138",
    "market": "US",
    "notes": [
      "Market US (United States)."
    ],
    "series": [
      {
        "day": "2026-09-29",
        "newVideos": 522
      },
      {
        "day": "2026-09-30",
        "newVideos": 873
      },
      {
        "day": "2026-10-01",
        "newVideos": 825
      }
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "summary": {
      "averagePerDay": 711.1,
      "days": 30,
      "last7Days": 4960,
      "peak": {
        "day": "2026-10-02",
        "value": 906
      },
      "previous7Days": 4316,
      "total": 21333,
      "unit": "new affiliate videos"
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.series`array
- `data.series[].day`string
- `data.series[].newVideos`integer
- `data.source`string
- `data.summary`object
- `data.summary.averagePerDay`number
- `data.summary.days`integer
- `data.summary.last7Days`integer
- `data.summary.peak`object
- `data.summary.peak.day`string
- `data.summary.peak.value`integer
- `data.summary.previous7Days`integer
- `data.summary.total`integer
- `data.summary.unit`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Videos selling its products, with revenue](https://tokconnect.com/docs/api/shops/#get-shops-id-videos)

`GET /v1/shops/{id}/videos`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Seller id (sellerId on products and stores).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop` tool with `method: videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "shop",
  "arguments": {
    "method": "videos",
    "id": "7495153913553128138"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/shops/7495153913553128138/videos" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/shops/7495153913553128138/videos", {
  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:

```json
{
  "data": {
    "count": 20,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": true,
    "id": "7495153913553128138",
    "items": [
      {
        "ad": 1,
        "ai_video": 0,
        "content_type": "video",
        "create_time": "2026/10/20 21:55:00",
        "description": "strawberries  #aftershaveoil #razorbumpsolutions #femininehygieneproducts #trulyaftershaveoil ",
        "duration": "41s",
        "handle": "petitetiramisu",
        "id": "7698933706576137485",
        "original_duration": 41.167,
        "product_ids": [
          "1729445990437982922"
        ],
        "revenue": "$35.51k",
        "sale": 1076,
        "uid": "6980982804826375173",
        "views": "3.6m"
      },
      {
        "ad": 1,
        "ai_video": 0,
        "content_type": "video",
        "create_time": "2026/09/29 17:49:11",
        "description": "Obsessed with this #lipgloss #drylips #lipcombo ",
        "duration": "37s",
        "handle": "swishybeauty",
        "id": "7691077500054637838",
        "original_duration": 37.867,
        "product_ids": [
          "1731896769144001226"
        ],
        "revenue": "$24.90k",
        "sale": 3113,
        "uid": "6672578604607685638",
        "views": "3.42m"
      },
      {
        "ad": 1,
        "ai_video": 0,
        "content_type": "video",
        "create_time": "2026/09/21 22:58:40",
        "description": "Now this is how you do a high shine gloss!😍🤏🏽🫦✨#trulylipgloss #trulybeauty #lipgloss #tiktokshopstockup ",
        "duration": "42s",
        "handle": "xoxopeta",
        "id": "7688188610041957662",
        "original_duration": 42.9,
        "product_ids": [
          "1731896769144001226"
        ],
        "revenue": "$23.14k",
        "sale": 2892,
        "uid": "7384276485555094570",
        "views": "3.3m"
      }
    ],
    "market": "US",
    "next": "eyJwYWdlIjoyLCJzaXplIjoyMH0",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyLCJzaXplIjoyMH0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.id`string
- `data.items`array
- `data.items[].ad`integer
- `data.items[].ai_video`integer
- `data.items[].content_type`string
- `data.items[].create_time`string
- `data.items[].description`string
- `data.items[].duration`string
- `data.items[].handle`string
- `data.items[].id`string
- `data.items[].original_duration`number
- `data.items[].product_ids`array
- `data.items[].revenue`string
- `data.items[].sale`integer
- `data.items[].uid`string
- `data.items[].views`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/shops/

---

# TikTok creator API

A creator's public profile and posts, and their TikTok Shop business: what they sell, for which brands, and who follows them.

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

Call these routes with your own key, or ask the same question in plain words.

[Get an API key](https://app.tokconnect.com/api-key)[Ask about a creator](https://app.tokconnect.com/?q=How%20much%20does%20%40dollskill%20sell%20on%20TikTok%20Shop%20and%20which%20products%20drive%20it%3F)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/creators/{id}`](https://tokconnect.com/docs/api/creators/#get-creators-id) | Followers, likes, videos, bio, link, Shop seller, ids |
| [GET `/v1/creators/{id}/audit`](https://tokconnect.com/docs/api/creators/#get-creators-id-audit) | Registered country and TikTok milestones |
| [GET `/v1/creators/{id}/embed`](https://tokconnect.com/docs/api/creators/#get-creators-id-embed) | Posts in the creator's embed widget |
| [GET `/v1/creators/{id}/followers`](https://tokconnect.com/docs/api/creators/#get-creators-id-followers) | Followers, when TikTok shows them (usually hidden) |
| [GET `/v1/creators/{id}/following`](https://tokconnect.com/docs/api/creators/#get-creators-id-following) | Accounts followed, when shown (usually hidden) |
| [GET `/v1/creators/{id}/lookalikes`](https://tokconnect.com/docs/api/creators/#get-creators-id-lookalikes) | Accounts TikTok suggests as similar |
| [GET `/v1/creators/{id}/playlists`](https://tokconnect.com/docs/api/creators/#get-creators-id-playlists) | Public playlists (ids for the playlists routes) |
| [GET `/v1/creators/{id}/posts`](https://tokconnect.com/docs/api/creators/#get-creators-id-posts) | Posts, newest first, with counts and linked products |
| [GET `/v1/creators/{id}/reposts`](https://tokconnect.com/docs/api/creators/#get-creators-id-reposts) | Posts the creator reposted |
| [GET `/v1/creators/{id}/collections`](https://tokconnect.com/docs/api/creators/#get-creators-id-collections) | Public saved collections (often empty) |
| [GET `/v1/creators/{id}/likes`](https://tokconnect.com/docs/api/creators/#get-creators-id-likes) | Public Liked tab (empty when hidden) |
| [GET `/v1/creators/{id}/shop/products`](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-products) | Products they sold, with revenue |
| [GET `/v1/creators/{id}/shop/sales`](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-sales) | Revenue, units, video vs LIVE, average price |
| [GET `/v1/creators/{id}/shop/shops`](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-shops) | Shops (brands) they sell for, with revenue |
| [GET `/v1/creators/{id}/shop/trend`](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-trend) | Daily revenue (up to ~13 months) |
| [GET `/v1/creators/{id}/shop/videos`](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-videos) | Their selling videos, with revenue |
| [GET `/v1/creators/{id}/shop/audience`](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-audience) | Follower age, gender, locations and active hours |
| [GET `/v1/creators/{id}/shop/linked-products`](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-linked-products) | Linked products in recent posts (views, not sales) |
| [GET `/v1/playlists/{id}`](https://tokconnect.com/docs/api/creators/#get-playlists-id) | Name, video count, owner |
| [GET `/v1/playlists/{id}/videos`](https://tokconnect.com/docs/api/creators/#get-playlists-id-videos) | The videos in it |

## Common parameters

These read the same on the routes below that take them.

- `region` (string): Market as an ISO country code, default US. Amounts are in the market's currency. See [Markets](https://tokconnect.com/docs/api/markets/).
- `window` (string): Date range ending at the last complete day (about 2 days ago). Default 30d. Use start and end for a custom range. **One of** `7d` `30d` `90d` `180d` `365d`.
- `start` (string): Custom range start, YYYY-MM-DD.
- `end` (string): Custom range end, YYYY-MM-DD (capped at the last complete day).
- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## One TikTok creator

One creator's public account: profile, posts, reposts, liked posts, followers, following, playlists and collections. Pass an @handle, a profile or video link, a secUid or a numeric id and TokConnect resolves the rest.

Profile counts are rounded the way the app shows them; for exact numbers call [`GET /v1/search/creators`](https://tokconnect.com/docs/api/search/#get-search-creators) with the handle. [`GET /v1/creators/{id}/audit`](https://tokconnect.com/docs/api/creators/#get-creators-id-audit) reports the account's registered country, ids and TikTok's milestones (started posting, follower marks); [`GET /v1/creators/{id}/lookalikes`](https://tokconnect.com/docs/api/creators/#get-creators-id-lookalikes) lists accounts TikTok suggests as similar.

### [Followers, likes, videos, bio, link, Shop seller, ids](https://tokconnect.com/docs/api/creators/#get-creators-id)

`GET /v1/creators/{id}`

1 credit per call

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: profile`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "profile",
    "id": "nike"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/nike" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/creators/nike", {
  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:

```json
{
  "data": {
    "bio": "Just Do It.",
    "bioLink": "http://empli.fi/niketiktok",
    "followers": 9345115,
    "following": 91,
    "handle": "nike",
    "id": "208464585232822272",
    "likes": 50478646,
    "nickname": "Nike",
    "secUid": "MS4wLjABAAAA…",
    "url": "https://www.tiktok.com/@nike",
    "videos": 1147
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.bio`string
- `data.bioLink`string
- `data.followers`integer
- `data.following`integer
- `data.handle`string
- `data.id`string
- `data.likes`integer
- `data.nickname`string
- `data.secUid`string
- `data.url`string
- `data.verified`boolean
- `data.videos`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Registered country and TikTok milestones](https://tokconnect.com/docs/api/creators/#get-creators-id-audit)

`GET /v1/creators/{id}/audit`

1 credit per call

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: audit`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "audit",
    "id": "nike"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/nike/audit" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/creators/nike/audit", {
  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:

```json
{
  "data": {
    "as_of": "2026-10-30T23:27:19Z",
    "country": "US",
    "followers": 9345458,
    "handle": "nike",
    "likes": 50478595,
    "milestones": [
      {
        "date": "2021-06-05",
        "title": "Reached 1M followers",
        "top_posts": [
          "6947750712164093189",
          "6960708098977729797",
          "6965902749355625734"
        ]
      },
      {
        "date": "2020-03-27",
        "title": "Reached 500K followers",
        "top_posts": [
          "6795435424132205829",
          "6797470670591741190",
          "6795576861863775493"
        ]
      },
      {
        "date": "2020-02-13",
        "title": "Reached 100K followers",
        "top_posts": [
          "6792724034258750726",
          "6792723599254981893",
          "6792722035081579782"
        ]
      }
    ],
    "nickname": "Nike",
    "notes": [
      "Calls made: TikTok's account-country lookup and its creator milestones.",
      "country is the country TikTok has on record for the account, not where its followers are.",
      "TikTok does not expose the account creation date; started_posting is the first milestone TikTok shows."
    ],
    "sec_uid": "MS4wLjABAAAA…",
    "see_also": [
      "creator method=profile id=@nike",
      "creator method=lookalikes id=@nike"
    ],
    "started_posting": "2017-03-24",
    "user_id": "208464585232822272"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.country`string
- `data.followers`integer
- `data.handle`string
- `data.likes`integer
- `data.milestones`array
- `data.milestones[].date`string
- `data.milestones[].title`string
- `data.milestones[].top_posts`array
- `data.nickname`string
- `data.notes`array
- `data.sec_uid`string
- `data.see_also`array
- `data.source`string
- `data.started_posting`string
- `data.user_id`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Posts in the creator's embed widget](https://tokconnect.com/docs/api/creators/#get-creators-id-embed)

`GET /v1/creators/{id}/embed`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.
- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: embed`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "embed",
    "id": "nike",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/nike/embed?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/creators/nike/embed?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": false,
    "videos": [
      {
        "caption": "Sculpted out of endless curiosity. Built for an obsession with better.  The Kobe 10 Protro arrives 8.23.",
        "comments": 0,
        "creator": {
          "handle": "nike",
          "secUid": "MS4wLjABAAAA…"
        },
        "id": "7670207038068215054",
        "likes": 0,
        "saves": 0,
        "shares": 0,
        "url": "https://www.tiktok.com/@nike/video/7670207038068215054",
        "views": 1100000
      },
      {
        "caption": "(✨️life changing title✨️)#kitten #why #confetti #weirdshithappenstome #whyandhowthefuckisthisconfettiflying",
        "comments": 0,
        "creator": {
          "handle": "ech0d0gg",
          "secUid": "MS4wLjABAAAA…"
        },
        "id": "7699977998820281620",
        "likes": 0,
        "saves": 0,
        "shares": 0,
        "url": "https://www.tiktok.com/@ech0d0gg/video/7699977998820281620",
        "views": 9000000
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.handle`string
- `data.videos[].creator.secUid`string
- `data.videos[].id`string
- `data.videos[].likes`integer
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Followers, when TikTok shows them (usually hidden)](https://tokconnect.com/docs/api/creators/#get-creators-id-followers)

`GET /v1/creators/{id}/followers`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.
- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: followers`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "followers",
    "id": "nike",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/nike/followers?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/creators/nike/followers?${params}`, {
  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:

```json
{
  "data": {
    "accounts": [
      {
        "followers": 864,
        "handle": "creator_1",
        "id": "7151412295716045870",
        "nickname": "Example creator 1",
        "secUid": "MS4wLjABAAAA…"
      },
      {
        "followers": 33,
        "handle": "creator_2",
        "id": "7510391742630282247",
        "nickname": "Example creator 2",
        "secUid": "MS4wLjABAAAA…"
      },
      {
        "followers": 227,
        "handle": "creator_3",
        "id": "7470355816270627883",
        "nickname": "Example creator 3",
        "secUid": "MS4wLjABAAAA…"
      }
    ],
    "hasMore": true,
    "max_time": 1793402802,
    "min_time": 1793402752,
    "myself_user_id": "0",
    "next": "eyJtYXhfY3Vyc29yIjoiMTc5MzQwMjgwMiIsIm1pbl9jdXJzb3IiOiIxNzkzNDAyNzUyIn0",
    "next_page_token": "eyJtYXhfY3Vyc29yIjoxNzkzNDAyNzc0LCJtaW5fY3Vyc29yIjoxNzkzNDAyNzUyfQ==",
    "version": "v2"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJtYXhfY3Vyc29yIjoiMTc5MzQwMjgwMiIsIm1pbl9jdXJzb3IiOiIxNzkzNDAyNzUyIn0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.accounts`array
- `data.accounts[].followers`integer
- `data.accounts[].handle`string
- `data.accounts[].id`string
- `data.accounts[].nickname`string
- `data.accounts[].secUid`string
- `data.accounts[].verified`boolean
- `data.hasMore`boolean
- `data.max_time`integer
- `data.min_time`integer
- `data.myself_user_id`string
- `data.next`string
- `data.next_page_token`string
- `data.version`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Accounts followed, when shown (usually hidden)](https://tokconnect.com/docs/api/creators/#get-creators-id-following)

`GET /v1/creators/{id}/following`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.
- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: following`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "following",
    "id": "tiktok",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/tiktok/following?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/creators/tiktok/following?${params}`, {
  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:

```json
{
  "data": {
    "accounts": [
      {
        "followers": 9000000,
        "handle": "creator_1",
        "id": "6551237489917432832",
        "nickname": "Example creator 1",
        "secUid": "MS4wLjABAAAA…"
      }
    ],
    "hasMore": false,
    "isTruncated": false
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.accounts`array
- `data.accounts[].followers`integer
- `data.accounts[].handle`string
- `data.accounts[].id`string
- `data.accounts[].nickname`string
- `data.accounts[].secUid`string
- `data.accounts[].verified`boolean
- `data.hasMore`boolean
- `data.isTruncated`boolean
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Accounts TikTok suggests as similar](https://tokconnect.com/docs/api/creators/#get-creators-id-lookalikes)

`GET /v1/creators/{id}/lookalikes`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.
- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: lookalikes`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "lookalikes",
    "id": "nike",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/nike/lookalikes?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/creators/nike/lookalikes?${params}`, {
  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:

```json
{
  "data": {
    "as_of": "2026-10-30T23:27:20Z",
    "count": 2,
    "has_more": true,
    "id": "nike",
    "items": [
      {
        "bio": "Energy, Uncompromised. \n\nIntentional energy to unlock clarity.",
        "followers": 34122,
        "handle": "drinkupdate",
        "likes": 911029,
        "nickname": "Update",
        "sec_uid": "MS4wLjABAAAA…",
        "user_id": "7579300616255718413",
        "videos": 55
      },
      {
        "bio": "The next generation of underwear and loungewear.",
        "followers": 3072432,
        "handle": "skims",
        "likes": 40256030,
        "nickname": "SKIMS",
        "sec_uid": "MS4wLjABAAAA…",
        "user_id": "6714013419890852870",
        "videos": 3246
      }
    ],
    "next": "eyJ0b2tlbiI6Ik16QT0ifQ",
    "notes": [
      "TikTok's own similar-account suggestions, in TikTok's order. Not ranked by TokConnect."
    ],
    "see_also": [
      "creator method=audit id=@<items[].handle>",
      "creator method=profile id=@<items[].handle>"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJ0b2tlbiI6Ik16QT0ifQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.count`integer
- `data.has_more`boolean
- `data.id`string
- `data.items`array
- `data.items[].bio`string
- `data.items[].followers`integer
- `data.items[].handle`string
- `data.items[].likes`integer
- `data.items[].nickname`string
- `data.items[].sec_uid`string
- `data.items[].user_id`string
- `data.items[].verified`boolean
- `data.items[].videos`integer
- `data.next`string
- `data.notes`array
- `data.see_also`array
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Public playlists (ids for the playlists routes)](https://tokconnect.com/docs/api/creators/#get-creators-id-playlists)

`GET /v1/creators/{id}/playlists`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.
- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: playlists`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "playlists",
    "id": "nike",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/nike/playlists?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/creators/nike/playlists?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJjdXJzb3IiOiIzIn0",
    "playlists": [
      {
        "creator": {
          "handle": "nike",
          "id": "208464585232822272",
          "nickname": "Nike",
          "secUid": "MS4wLjABAAAA…"
        },
        "id": "7628692798685940494",
        "name": "Athlete Versus",
        "videos": 4
      },
      {
        "creator": {
          "handle": "nike",
          "id": "208464585232822272",
          "nickname": "Nike",
          "secUid": "MS4wLjABAAAA…"
        },
        "id": "7352922358623062826",
        "name": "Air Max Dn BTS",
        "videos": 5
      },
      {
        "creator": {
          "handle": "nike",
          "id": "208464585232822272",
          "nickname": "Nike",
          "secUid": "MS4wLjABAAAA…"
        },
        "id": "7268891136851413806",
        "name": "1000Victories",
        "videos": 19
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOiIzIn0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.playlists`array
- `data.playlists[].creator`object
- `data.playlists[].creator.handle`string
- `data.playlists[].creator.id`string
- `data.playlists[].creator.nickname`string
- `data.playlists[].creator.secUid`string
- `data.playlists[].id`string
- `data.playlists[].name`string
- `data.playlists[].videos`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Posts, newest first, with counts and linked products](https://tokconnect.com/docs/api/creators/#get-creators-id-posts)

`GET /v1/creators/{id}/posts`

1 credit per call · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.
- `limit` (integer): Results per page. Max 35. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: posts`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "posts",
    "id": "nike",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/nike/posts?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/creators/nike/posts?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJjdXJzb3IiOjE3OTMyNDM2NjYwMDB9",
    "videos": [
      {
        "caption": "Welcome to New York City. This tour is 26.2 miles and will take everything you've got. See you at the finish. #nikerunning #fiveboroughs #marathon #fyp",
        "comments": 30,
        "creator": {
          "handle": "nike",
          "id": "208464585232822272",
          "nickname": "Nike",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 13,
        "hashtags": [
          {
            "id": "13020056",
            "name": "nikerunning"
          },
          {
            "id": "77850878",
            "name": "fiveboroughs"
          }
        ],
        "id": "7702531221674347789",
        "language": "en",
        "likes": 590,
        "posted": "2026-10-30T18:35:40Z",
        "saves": 12,
        "shares": 7,
        "sound": {
          "author": "Nike",
          "id": "7702531360175098638",
          "original": true,
          "title": "原声 - Nike"
        },
        "url": "https://www.tiktok.com/@nike/video/7702531221674347789",
        "views": 8168
      },
      {
        "caption": "Nike Jewelry just landed. Check the SNKRS app for more. #nike #jewelry #fyp",
        "comments": 50,
        "creator": {
          "handle": "nike",
          "id": "208464585232822272",
          "nickname": "Nike",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 7,
        "hashtags": [
          {
            "id": "9789",
            "name": "nike"
          },
          {
            "id": "21519",
            "name": "jewelry"
          }
        ],
        "id": "7702142102230158606",
        "language": "en",
        "likes": 2596,
        "posted": "2026-10-29T17:25:17Z",
        "saves": 104,
        "shares": 28,
        "sound": {
          "author": "Nike",
          "id": "7702142090700180238",
          "original": true,
          "title": "原声 - Nike"
        },
        "url": "https://www.tiktok.com/@nike/video/7702142102230158606",
        "views": 35963
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOjE3OTMyNDM2NjYwMDB9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].creator.verified`boolean
- `data.videos[].durationSec`integer
- `data.videos[].hashtags`array
- `data.videos[].hashtags[].id`string
- `data.videos[].hashtags[].name`string
- `data.videos[].id`string
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.original`boolean
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Posts the creator reposted](https://tokconnect.com/docs/api/creators/#get-creators-id-reposts)

`GET /v1/creators/{id}/reposts`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.
- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: reposts`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "reposts",
    "id": "nike",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/nike/reposts?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/creators/nike/reposts?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJjdXJzb3IiOiIzIn0",
    "videos": [
      {
        "caption": "Golden boots for a golden player ✨",
        "comments": 74,
        "creator": {
          "followers": 67500,
          "handle": "londoncitylionesses",
          "id": "6815596123420525573",
          "nickname": "londoncitylionesses",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 46,
        "id": "7701372324020276502",
        "language": "en",
        "likes": 14600,
        "posted": "2026-10-27T15:38:02Z",
        "saves": 1053,
        "shares": 482,
        "sound": {
          "author": "londoncitylionesses",
          "id": "7701372337848961814",
          "original": true,
          "title": "original sound"
        },
        "url": "https://www.tiktok.com/@londoncitylionesses/video/7701372324020276502",
        "views": 118900
      },
      {
        "caption": "Alpha Chi ❤︎’s @Nike  Shoutout to Nike for gifting our new member class their new Studio Fleece! Seriously the best sweatsets ever! #nikeaxo #studiofleece #nike #sorority #universityofsouthcarolina",
        "comments": 222,
        "creator": {
          "followers": 39900,
          "handle": "alphachiuofsc",
          "id": "7047632338502796334",
          "nickname": "ALPHA CHI USC",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 11,
        "hashtags": [
          {
            "id": "7677236652473286669",
            "name": "nikeaxo"
          },
          {
            "id": "7662951028928544782",
            "name": "studiofleece"
          }
        ],
        "id": "7677263890794761503",
        "language": "en",
        "likes": 26300,
        "posted": "2026-08-23T16:25:13Z",
        "saves": 546,
        "shares": 1031,
        "sound": {
          "author": "twokay",
          "id": "7531317665290390273",
          "original": true,
          "title": "original sound"
        },
        "url": "https://www.tiktok.com/@alphachiuofsc/video/7677263890794761503",
        "views": 488800
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOiIzIn0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.followers`integer
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].durationSec`integer
- `data.videos[].id`string
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.original`boolean
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Public saved collections (often empty)](https://tokconnect.com/docs/api/creators/#get-creators-id-collections)

`GET /v1/creators/{id}/collections`

1 credit per call · Paged · Often empty

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.
- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: collections`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "collections",
    "id": "nike",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/nike/collections?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/creators/nike/collections?${params}`, {
  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 (this capture matched nothing):

```json
{
  "data": {
    "hasMore": false,
    "playlists": []
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.playlists`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Public Liked tab (empty when hidden)](https://tokconnect.com/docs/api/creators/#get-creators-id-likes)

`GET /v1/creators/{id}/likes`

1 credit per call · Paged · Often empty

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.
- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator` tool with `method: likes`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator",
  "arguments": {
    "method": "likes",
    "id": "nike",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/nike/likes?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/creators/nike/likes?${params}`, {
  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 (this capture matched nothing):

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJjdXJzb3IiOiIxNzkzMTQzODIxMDAwIn0",
    "videos": []
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOiIxNzkzMTQzODIxMDAwIn0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.videos`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## A creator's TikTok Shop business

What a creator sells. Linked products (products linked in recent posts, with views, no sales) come live from TikTok. Sales, trend, products, brands, selling videos and audience (follower age, gender, locations, languages) come from Shop Analytics in any market via region. Use them to vet affiliates.

Number formats: Shop Analytics money and count fields are display strings such as "$40.66k"; the trend route returns numbers. Audience says so when TokConnect has no data for the creator.

### [Products they sold, with revenue](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-products)

`GET /v1/creators/{id}/shop/products`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_commerce` tool with `method: products`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_commerce",
  "arguments": {
    "method": "products",
    "id": "6963732702017668101"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/6963732702017668101/shop/products" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/creators/6963732702017668101/shop/products", {
  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:

```json
{
  "data": {
    "count": 20,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": true,
    "id": "6963732702017668101",
    "items": [
      {
        "id": "1732479640669033376",
        "product_title": "Shark FacialPro Glow At Home Facial System - FH320",
        "revenue": "$40.66k",
        "sale": "136",
        "seller_id": "7494661364292028320",
        "unit_price": "$299.00"
      },
      {
        "id": "1732571163004670880",
        "product_title": "Shark FacialPro Glow At Home Hydrating Facial System - FH310",
        "revenue": "$28.39k",
        "sale": "114",
        "seller_id": "7494661364292028320",
        "unit_price": "$249.00"
      },
      {
        "id": "1732479644677411744",
        "product_title": "Shark Beauty SilkiPro Hair Straightener and Dryer - HT400",
        "revenue": "$25.07k",
        "sale": "126",
        "seller_id": "7494661364292028320",
        "unit_price": "$199.00"
      }
    ],
    "market": "US",
    "next": "eyJwYWdlIjoyLCJzaXplIjoyMH0",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyLCJzaXplIjoyMH0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.id`string
- `data.items`array
- `data.items[].id`string
- `data.items[].product_title`string
- `data.items[].revenue`string
- `data.items[].sale`string
- `data.items[].seller_id`string
- `data.items[].unit_price`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Revenue, units, video vs LIVE, average price](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-sales)

`GET /v1/creators/{id}/shop/sales`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_commerce` tool with `method: sales`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_commerce",
  "arguments": {
    "method": "sales",
    "id": "6963732702017668101"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/6963732702017668101/shop/sales" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/creators/6963732702017668101/shop/sales", {
  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:

```json
{
  "data": {
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "6963732702017668101",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totals": {
      "day_followers": "396",
      "day_live_revenue": "$7.96k",
      "day_live_views": "17.7k",
      "day_revenue": "$8.03k",
      "day_sale": "36.4",
      "day_shop_revenue": "$69.16",
      "day_video_revenue": "$0.00",
      "day_video_views": "299.44k",
      "followers": "11.9k",
      "live_revenue": "$238.91k",
      "live_views": "531.01k",
      "revenue": "$240.98k",
      "sale": "1.09k",
      "shop_revenue": "$2.07k",
      "unit_price": "$220.68",
      "video_revenue": "$0.00",
      "video_views": "8.98m"
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.totals`object
- `data.totals.day_followers`string
- `data.totals.day_live_revenue`string
- `data.totals.day_live_views`string
- `data.totals.day_revenue`string
- `data.totals.day_sale`string
- `data.totals.day_shop_revenue`string
- `data.totals.day_video_revenue`string
- `data.totals.day_video_views`string
- `data.totals.followers`string
- `data.totals.live_revenue`string
- `data.totals.live_views`string
- `data.totals.revenue`string
- `data.totals.sale`string
- `data.totals.shop_revenue`string
- `data.totals.unit_price`string
- `data.totals.video_revenue`string
- `data.totals.video_views`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Shops (brands) they sell for, with revenue](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-shops)

`GET /v1/creators/{id}/shop/shops`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_commerce` tool with `method: shops`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_commerce",
  "arguments": {
    "method": "shops",
    "id": "6963732702017668101"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/6963732702017668101/shop/shops" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/creators/6963732702017668101/shop/shops", {
  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:

```json
{
  "data": {
    "count": 1,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": false,
    "id": "6963732702017668101",
    "items": [
      {
        "live_revenue": "$238.91k",
        "product_count": "21",
        "revenue": "$240.98k",
        "sale": "1.09k",
        "seller_id": "7494661364292028320",
        "seller_type": "BRAND",
        "shop_name": "Shark Beauty",
        "video_revenue": "$0.00"
      }
    ],
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.id`string
- `data.items`array
- `data.items[].live_revenue`string
- `data.items[].product_count`string
- `data.items[].revenue`string
- `data.items[].sale`string
- `data.items[].seller_id`string
- `data.items[].seller_type`string
- `data.items[].shop_name`string
- `data.items[].video_revenue`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Daily revenue (up to ~13 months)](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-trend)

`GET /v1/creators/{id}/shop/trend`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_commerce` tool with `method: trend`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_commerce",
  "arguments": {
    "method": "trend",
    "id": "6963732702017668101"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/6963732702017668101/shop/trend" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/creators/6963732702017668101/shop/trend", {
  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:

```json
{
  "data": {
    "coverage": {
      "days": 27,
      "daysWithSales": 23,
      "firstDayWithSales": "2026-10-02"
    },
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "6963732702017668101",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD.",
      "First day with recorded sales in this window: 2026-10-02."
    ],
    "series": [
      {
        "content_views": 238295,
        "followers": 400,
        "live_revenue": 9454.86,
        "live_views": 14021,
        "partition_day": "2026-10-02",
        "revenue": 9572.82,
        "sale": 44,
        "unit_price": 217.56,
        "video_revenue": 0,
        "video_views": 224274
      },
      {
        "content_views": 291172,
        "followers": 300,
        "live_revenue": 0,
        "live_views": 0,
        "partition_day": "2026-10-03",
        "revenue": 78,
        "sale": 2,
        "unit_price": 39,
        "video_revenue": 0,
        "video_views": 291172
      },
      {
        "content_views": 1529670,
        "followers": 500,
        "live_revenue": 21725.95,
        "live_views": 42909,
        "partition_day": "2026-10-04",
        "revenue": 21842.95,
        "sale": 92,
        "unit_price": 237.42,
        "video_revenue": 0,
        "video_views": 1486761
      }
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totals": {
      "revenue": 240984,
      "units": 1092
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.coverage`object
- `data.coverage.days`integer
- `data.coverage.daysWithSales`integer
- `data.coverage.firstDayWithSales`string
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.series`array
- `data.series[].content_views`integer
- `data.series[].followers`integer
- `data.series[].live_revenue`number
- `data.series[].live_views`integer
- `data.series[].partition_day`string
- `data.series[].revenue`number
- `data.series[].sale`integer
- `data.series[].unit_price`number
- `data.series[].video_revenue`integer
- `data.series[].video_views`integer
- `data.source`string
- `data.totals`object
- `data.totals.revenue`integer
- `data.totals.units`integer
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Their selling videos, with revenue](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-videos)

`GET /v1/creators/{id}/shop/videos`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_commerce` tool with `method: videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_commerce",
  "arguments": {
    "method": "videos",
    "id": "6963732702017668101"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/6963732702017668101/shop/videos" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/creators/6963732702017668101/shop/videos", {
  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:

```json
{
  "data": {
    "count": 20,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": true,
    "id": "6963732702017668101",
    "items": [
      {
        "ad": 0,
        "ad2Cost": "$0.00",
        "ad2Roas": 0,
        "ad_cpa": 0,
        "ad_revenue_ratio": "0%",
        "ad_view_ratio": "0%",
        "ai_video": 0,
        "collect_day": "2026-10-26",
        "content_type": "video",
        "create_time": "2026/10/26 09:55:54",
        "creator_uid": "6963732702017668101",
        "description": "Don’t miss @Chrisappleton1 LIVE tonight on our TikTok! Who's in? 👀 #sharkbeauty #chrisappleton #tiktoklive #tiktokshop #hairtutorial",
        "duration": "12s",
        "follower_count": 278600,
        "gpm": 0,
        "handle": "sharkbeauty",
        "id": "7700974905965268237",
        "original_duration": 12,
        "product_ids": [],
        "revenue": "$0.00",
        "sale": "0",
        "views": "6.5k"
      },
      {
        "ad": 0,
        "ad2Cost": "$0.00",
        "ad2Roas": 0,
        "ad_cpa": 0,
        "ad_revenue_ratio": "0%",
        "ad_view_ratio": "0%",
        "ai_video": 0,
        "collect_day": "2026-10-01",
        "content_type": "video",
        "create_time": "2026/10/01 15:53:28",
        "creator_uid": "6963732702017668101",
        "description": "National Hair Day calls for two things: bouncy blowouts and shopping early prime day deals sale on @amazon . 🍒✨ Shop FlexStlye now. #sharkbeauty #sharkflexstyle #amazon #primeday #nationalhairday",
        "duration": "18s",
        "follower_count": 278100,
        "gpm": 0,
        "handle": "sharkbeauty",
        "id": "7691789893600562446",
        "original_duration": 18,
        "product_ids": [],
        "revenue": "$0.00",
        "sale": "0",
        "views": "12.08k"
      },
      {
        "ad": 0,
        "ad2Cost": "$0.00",
        "ad2Roas": 0,
        "ad_cpa": 0,
        "ad_revenue_ratio": "0%",
        "ad_view_ratio": "0%",
        "ai_video": 0,
        "collect_day": "2026-10-05",
        "content_type": "video",
        "create_time": "2026/10/05 10:38:44",
        "creator_uid": "6963732702017668101",
        "description": "Gentle on the skin, big on the glow. ✨Shop now. #sharkbeauty #sharkfacialproglow #gentle #dermdetox #sensitiveskin",
        "duration": "16s",
        "follower_count": 278600,
        "gpm": 0,
        "handle": "sharkbeauty",
        "id": "7693193061777591565",
        "original_duration": 16,
        "product_ids": [],
        "revenue": "$0.00",
        "sale": "0",
        "views": "4.36k"
      }
    ],
    "market": "US",
    "next": "eyJwYWdlIjoyLCJzaXplIjoyMH0",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyLCJzaXplIjoyMH0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.id`string
- `data.items`array
- `data.items[].ad`integer
- `data.items[].ad2Cost`string
- `data.items[].ad2Roas`integer
- `data.items[].ad_cpa`integer
- `data.items[].ad_revenue_ratio`string
- `data.items[].ad_view_ratio`string
- `data.items[].ai_video`integer
- `data.items[].collect_day`string
- `data.items[].content_type`string
- `data.items[].create_time`string
- `data.items[].creator_uid`string
- `data.items[].description`string
- `data.items[].duration`string
- `data.items[].follower_count`integer
- `data.items[].gpm`integer
- `data.items[].handle`string
- `data.items[].id`string
- `data.items[].original_duration`integer
- `data.items[].product_ids`array
- `data.items[].revenue`string
- `data.items[].sale`string
- `data.items[].views`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Follower age, gender, locations and active hours](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-audience)

`GET /v1/creators/{id}/shop/audience`

1 credit per call · Shop Analytics · Paged · Often empty · 17 markets

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_commerce` tool with `method: audience`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_commerce",
  "arguments": {
    "method": "audience",
    "id": "6963732702017668101"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/6963732702017668101/shop/audience" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/creators/6963732702017668101/shop/audience", {
  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 (this capture matched nothing):

```json
{
  "data": {
    "audience": null,
    "dataEnd": "2026-10-28",
    "id": "6963732702017668101",
    "market": "US",
    "notes": [
      "Market US (United States).",
      "The source has not built this creator's audience breakdown yet, so there is no follower age, gender, location or language data to report. Try again later; no other tool returns it."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "status": "not_built",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.audience`null
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.status`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Linked products in recent posts (views, not sales)](https://tokconnect.com/docs/api/creators/#get-creators-id-shop-linked-products)

`GET /v1/creators/{id}/shop/linked-products`

1 credit per call · Often empty

#### Parameters

- `id` (string, path, required): Creator: @handle, profile or video link, secUid (MS4wLjAB...) or numeric user id. TokConnect looks up the ids it needs.

**1 more optional parameter**

- `max_pages` (integer): Post pages to scan, 15 posts each (default 3, max 5).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_commerce` tool with `method: linked_products`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_commerce",
  "arguments": {
    "method": "linked_products",
    "id": "6963732702017668101"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creators/6963732702017668101/shop/linked-products" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/creators/6963732702017668101/shop/linked-products", {
  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 (this capture matched nothing):

```json
{
  "data": {
    "creator": {
      "followers": 279536,
      "handle": "sharkbeauty",
      "nickname": "Shark Beauty",
      "secUid": "MS4wLjABAAAA…"
    },
    "from": "2026-09-30",
    "note": "Products linked in the creator's recent public posts (TikTok Shop links on videos). Not the full showcase tab, and not sales.",
    "postsWithProducts": 0,
    "productCount": 0,
    "products": [],
    "scannedPosts": 45,
    "to": "2026-10-30"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.creator`object
- `data.creator.followers`integer
- `data.creator.handle`string
- `data.creator.nickname`string
- `data.creator.secUid`string
- `data.creator.verified`boolean
- `data.from`string
- `data.note`string
- `data.postsWithProducts`integer
- `data.productCount`integer
- `data.products`array
- `data.scannedPosts`integer
- `data.to`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## One playlist or collection

One creator playlist or saved collection (id from [`GET /v1/creators/{id}/playlists`](https://tokconnect.com/docs/api/creators/#get-creators-id-playlists) or [`GET /v1/creators/{id}/collections`](https://tokconnect.com/docs/api/creators/#get-creators-id-collections)): detail or its videos.

### [Name, video count, owner](https://tokconnect.com/docs/api/creators/#get-playlists-id)

`GET /v1/playlists/{id}`

1 credit per call

#### Parameters

- `id` (string, path, required): Playlist or collection id.

**1 more optional parameter**

- `kind` (string): playlist (default) or collection. **One of** `playlist` `collection`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_playlist` tool with `method: detail`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_playlist",
  "arguments": {
    "method": "detail",
    "id": "7628692798685940494"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/playlists/7628692798685940494" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/playlists/7628692798685940494", {
  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:

```json
{
  "data": {
    "creator": {
      "handle": "nike",
      "id": "208464585232822272",
      "nickname": "Nike",
      "secUid": "MS4wLjABAAAA…"
    },
    "id": "7628692798685940494",
    "name": "Athlete Versus",
    "videos": 4
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.creator`object
- `data.creator.handle`string
- `data.creator.id`string
- `data.creator.nickname`string
- `data.creator.secUid`string
- `data.id`string
- `data.name`string
- `data.videos`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [The videos in it](https://tokconnect.com/docs/api/creators/#get-playlists-id-videos)

`GET /v1/playlists/{id}/videos`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Playlist or collection id.
- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `kind` (string): playlist (default) or collection. **One of** `playlist` `collection`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_playlist` tool with `method: videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_playlist",
  "arguments": {
    "method": "videos",
    "id": "7628692798685940494",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/playlists/7628692798685940494/videos?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/playlists/7628692798685940494/videos?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJjdXJzb3IiOiIzIn0",
    "videos": [
      {
        "allowsAdUse": true,
        "caption": "@A’ja Wilson has been and forever will be a bucket 🪣",
        "comments": 82,
        "creator": {
          "followers": 9300000,
          "handle": "nike",
          "id": "208464585232822272",
          "nickname": "Nike",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 78,
        "id": "7611313628892908814",
        "isAd": true,
        "language": "en",
        "likes": 4538,
        "posted": "2026-02-26T23:04:22Z",
        "saves": 222,
        "shares": 165,
        "sound": {
          "author": "Nike",
          "id": "7611313645716507405",
          "original": true,
          "title": "original sound"
        },
        "url": "https://www.tiktok.com/@nike/video/7611313628892908814",
        "views": 102300
      },
      {
        "allowsAdUse": true,
        "caption": "Sabrina Ionescu isn’t new to this",
        "comments": 77,
        "creator": {
          "followers": 9300000,
          "handle": "nike",
          "id": "208464585232822272",
          "nickname": "Nike",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 76,
        "id": "7628691578630032653",
        "isAd": true,
        "language": "en",
        "likes": 2677,
        "posted": "2026-04-14T19:00:22Z",
        "saves": 147,
        "shares": 81,
        "sound": {
          "author": "Nike",
          "id": "7628691779193211662",
          "original": true,
          "title": "original sound"
        },
        "url": "https://www.tiktok.com/@nike/video/7628691578630032653",
        "views": 170100
      },
      {
        "allowsAdUse": true,
        "caption": "We all know Nelly Korda can sink putts but she can sink some baskets too.",
        "comments": 152,
        "creator": {
          "followers": 9300000,
          "handle": "nike",
          "id": "208464585232822272",
          "nickname": "Nike",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 84,
        "id": "7629804861051161869",
        "isAd": true,
        "language": "en",
        "likes": 2189,
        "posted": "2026-04-17T19:00:09Z",
        "saves": 136,
        "shares": 115,
        "sound": {
          "author": "Nike",
          "id": "7629804938620685069",
          "original": true,
          "title": "original sound"
        },
        "url": "https://www.tiktok.com/@nike/video/7629804861051161869",
        "views": 184000
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOiIzIn0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.videos`array
- `data.videos[].allowsAdUse`boolean
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.followers`integer
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].creator.verified`boolean
- `data.videos[].durationSec`integer
- `data.videos[].id`string
- `data.videos[].isAd`boolean
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.original`boolean
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Vet a creator before you pay them.

[Ask about a creator](https://app.tokconnect.com/?q=How%20much%20does%20%40dollskill%20sell%20on%20TikTok%20Shop%20and%20which%20products%20drive%20it%3F)[Get an API key](https://app.tokconnect.com/api-key)

Source: https://tokconnect.com/docs/api/creators/

---

# TikTok video API

One video or photo post: counts, comments, transcript, similar videos and the sales it drove. Plus samples of TikTok's own feeds and a fair comment giveaway draw.

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

Call these routes with your own key, or ask the same question in plain words. No code? Use the free [transcript generator](https://tokconnect.com/tools/tiktok-transcript-generator/), [comment viewer](https://tokconnect.com/tools/tiktok-comment-viewer/) or [giveaway picker](https://tokconnect.com/tools/tiktok-giveaway-picker/).

[Get an API key](https://app.tokconnect.com/api-key)[Ask about a video](https://app.tokconnect.com/?q=What%20do%20people%20say%20in%20the%20comments%20of%20this%20TikTok%20video%3F)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/videos/{id}`](https://tokconnect.com/docs/api/videos/#get-videos-id) | Counts, creator, hashtags, sound, place, linked products, caption tracks |
| [GET `/v1/videos/{id}/captions`](https://tokconnect.com/docs/api/videos/#get-videos-id-captions) | One caption file as WebVTT (subtitle_url, or the video id: English track first) |
| [GET `/v1/videos/{id}/comment-themes`](https://tokconnect.com/docs/api/videos/#get-videos-id-comment-themes) | Keywords TikTok extracts from the comments, with sample comments |
| [GET `/v1/videos/{id}/comments`](https://tokconnect.com/docs/api/videos/#get-videos-id-comments) | Top-level comments |
| [GET `/v1/videos/{id}/product-trend`](https://tokconnect.com/docs/api/videos/#get-videos-id-product-trend) | Daily sales of the video's products |
| [GET `/v1/videos/{id}/products`](https://tokconnect.com/docs/api/videos/#get-videos-id-products) | Products sold through the video, with revenue |
| [GET `/v1/videos/{id}/sales`](https://tokconnect.com/docs/api/videos/#get-videos-id-sales) | Revenue, units and ad metrics the video drove |
| [GET `/v1/videos/{id}/similar`](https://tokconnect.com/docs/api/videos/#get-videos-id-similar) | Videos TikTok relates to this one |
| [GET `/v1/videos/{id}/similar-revenue`](https://tokconnect.com/docs/api/videos/#get-videos-id-similar-revenue) | How similar videos performed |
| [GET `/v1/videos/{id}/transcript`](https://tokconnect.com/docs/api/videos/#get-videos-id-transcript) | Existing captions as plain text (nothing is transcribed) |
| [GET `/v1/videos/{id}/comments/{comment_id}/replies`](https://tokconnect.com/docs/api/videos/#get-videos-id-comments-comment-id-replies) | Replies to one comment (comment_id) |
| [GET `/v1/feeds/discover`](https://tokconnect.com/docs/api/videos/#get-feeds-discover) | Discover picks: creators, hashtags, sounds |
| [GET `/v1/feeds/discover/hashtags`](https://tokconnect.com/docs/api/videos/#get-feeds-discover-hashtags) | Discover hashtags with sample videos |
| [GET `/v1/feeds/explore`](https://tokconnect.com/docs/api/videos/#get-feeds-explore) | Videos from one Explore category |
| [GET `/v1/feeds/for-you`](https://tokconnect.com/docs/api/videos/#get-feeds-for-you) | A page of the For You feed |
| [POST `/v1/videos/{video}/giveaway`](https://tokconnect.com/docs/api/videos/#post-videos-video-giveaway) | Comment giveaway draw |

## Common parameters

These read the same on the routes below that take them.

- `region` (string): Market as an ISO country code, default US. Amounts are in the market's currency. See [Markets](https://tokconnect.com/docs/api/markets/).
- `window` (string): Date range ending at the last complete day (about 2 days ago). Default 30d. Use start and end for a custom range. **One of** `7d` `30d` `90d` `180d` `365d`.
- `start` (string): Custom range start, YYYY-MM-DD.
- `end` (string): Custom range end, YYYY-MM-DD (capped at the last complete day).
- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## One TikTok video

Everything about one video or photo post: detail, comments, replies, comment themes, caption transcript and similar videos. The Shop Analytics routes show the revenue the video drove and the products it sold, in the market you pick with region.

Use the post id or a link from any other route. Comment themes lists the keywords TikTok extracts from the comments, each with sample comments.

### [Counts, creator, hashtags, sound, place, linked products, caption tracks](https://tokconnect.com/docs/api/videos/#get-videos-id)

`GET /v1/videos/{id}`

1 credit per call · 17 markets

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: detail`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "detail",
    "id": "7691522530129022221"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7691522530129022221" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/7691522530129022221", {
  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:

```json
{
  "data": {
    "caption": "the shiniest lips on the internet  @NOONI #noonipartner    #beauty #glitterlips #lipoil #kbeauty",
    "comments": 20,
    "creator": {
      "handle": "ingaterner",
      "id": "6915470077362865158",
      "nickname": "Inga Terner",
      "secUid": "MS4wLjABAAAA…"
    },
    "durationSec": 18,
    "hashtags": [
      {
        "id": "7305074851570516011",
        "name": "noonipartner"
      },
      {
        "id": "5393",
        "name": "beauty"
      },
      {
        "id": "206503",
        "name": "glitterlips"
      }
    ],
    "id": "7691522530129022221",
    "language": "en",
    "likes": 1049,
    "posted": "2026-10-01T02:36:03Z",
    "saves": 207,
    "shares": 39,
    "sound": {
      "author": "JERI",
      "id": "7139362230881094442",
      "original": true,
      "title": "ariana grande . ill do it"
    },
    "url": "https://www.tiktok.com/@ingaterner/video/7691522530129022221",
    "views": 22632
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.caption`string
- `data.comments`integer
- `data.creator`object
- `data.creator.handle`string
- `data.creator.id`string
- `data.creator.nickname`string
- `data.creator.secUid`string
- `data.durationSec`integer
- `data.hashtags`array
- `data.hashtags[].id`string
- `data.hashtags[].name`string
- `data.id`string
- `data.language`string
- `data.likes`integer
- `data.posted`string
- `data.saves`integer
- `data.shares`integer
- `data.sound`object
- `data.sound.author`string
- `data.sound.id`string
- `data.sound.original`boolean
- `data.sound.title`string
- `data.url`string
- `data.views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [One caption file as WebVTT (subtitle_url, or the video id: English track first)](https://tokconnect.com/docs/api/videos/#get-videos-id-captions)

`GET /v1/videos/{id}/captions`

1 credit per call

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).

**1 more optional parameter**

- `subtitle_url` (string): A caption URL from [`GET /v1/videos/{id}`](https://tokconnect.com/docs/api/videos/#get-videos-id) (`captions[].url`).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: captions`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "captions",
    "id": "7691388445251439924"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7691388445251439924/captions" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/7691388445251439924/captions", {
  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

No recorded example for this route yet. A success uses the usual envelope: the route's JSON under `data`, `next_cursor` when there is another page, and `meta` with the credits charged. See [pagination](https://tokconnect.com/docs/api/pagination/).

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Keywords TikTok extracts from the comments, with sample comments](https://tokconnect.com/docs/api/videos/#get-videos-id-comment-themes)

`GET /v1/videos/{id}/comment-themes`

1 credit per call

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: comment_themes`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "comment_themes",
    "id": "7691522530129022221"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7691522530129022221/comment-themes" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/7691522530129022221/comment-themes", {
  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:

```json
{
  "data": {
    "as_of": "2026-10-30T23:27:21Z",
    "count": 2,
    "has_more": false,
    "id": "7691522530129022221",
    "items": [
      {
        "keyword": "looks amazing",
        "sample_count": 1,
        "samples": [
          {
            "date": "2026-10-02",
            "id": "7692112068871275295",
            "likes": 1,
            "text": "Wow looks amazing"
          }
        ]
      },
      {
        "keyword": "blonde hair",
        "sample_count": 1,
        "samples": [
          {
            "date": "2026-10-01",
            "id": "7691593645211861782",
            "likes": 1,
            "text": "Hello There Inga i like very much how are You make-up and how lip-gloss you used in your make-up and she's stay very good and beautiful with your blonde hair Inga"
          }
        ]
      }
    ],
    "notes": [
      "Keywords are TikTok's own extraction from the comments, in TikTok's order; sample_count is how many sample comments TikTok attached, not a total."
    ],
    "see_also": [
      "video method=comments id=7691522530129022221"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.count`integer
- `data.has_more`boolean
- `data.id`string
- `data.items`array
- `data.items[].keyword`string
- `data.items[].sample_count`integer
- `data.items[].samples`array
- `data.items[].samples[].date`string
- `data.items[].samples[].id`string
- `data.items[].samples[].likes`integer
- `data.items[].samples[].text`string
- `data.notes`array
- `data.see_also`array
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Top-level comments](https://tokconnect.com/docs/api/videos/#get-videos-id-comments)

`GET /v1/videos/{id}/comments`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).
- `limit` (integer): Results per page. Max 50. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `sort` (string): Relevant (TikTok's order, default) or newest. **One of** `relevant` `newest`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: comments`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "comments",
    "id": "7691522530129022221",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7691522530129022221/comments?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/videos/7691522530129022221/comments?${params}`, {
  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:

```json
{
  "data": {
    "comments": [
      {
        "author": {
          "handle": "analuaviibe",
          "nickname": "analuaviibe",
          "secUid": "MS4wLjABAAAA…"
        },
        "id": "7693243163997602574",
        "likes": 0,
        "posted": "2026-10-05T17:53:31Z",
        "replies": 1,
        "text": "Did you use another product before the lip oil?"
      },
      {
        "author": {
          "handle": "tarapr1",
          "nickname": "TaraPrit",
          "secUid": "MS4wLjABAAAA…"
        },
        "id": "7698536869424726785",
        "likes": 0,
        "posted": "2026-10-20T00:15:26Z",
        "text": "All of those colours r so pretty!!!"
      },
      {
        "author": {
          "handle": "kc90887",
          "nickname": "KC",
          "secUid": "MS4wLjABAAAA…"
        },
        "id": "7701658459657306912",
        "likes": 0,
        "posted": "2026-10-28T10:08:41Z",
        "text": "Hammer geile Frau 😍🤗"
      }
    ],
    "hasMore": true,
    "next": "eyJjdXJzb3IiOjN9",
    "total": 20
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOjN9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.comments`array
- `data.comments[].author`object
- `data.comments[].author.handle`string
- `data.comments[].author.nickname`string
- `data.comments[].author.secUid`string
- `data.comments[].id`string
- `data.comments[].likes`integer
- `data.comments[].posted`string
- `data.comments[].replies`integer
- `data.comments[].text`string
- `data.hasMore`boolean
- `data.next`string
- `data.total`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Daily sales of the video's products](https://tokconnect.com/docs/api/videos/#get-videos-id-product-trend)

`GET /v1/videos/{id}/product-trend`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: product_trend`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "product_trend",
    "id": "7700682843906723103"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7700682843906723103/product-trend" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/7700682843906723103/product-trend", {
  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:

```json
{
  "data": {
    "currency": "USD",
    "daily": [
      {
        "ad": 0,
        "adTotalCost": 0,
        "adTotalRoas": 0,
        "ad_revenue_ratio": 0,
        "ad_view_ratio": 0,
        "new_followers": 0,
        "partition_day": "2026-09-29",
        "revenue": 0,
        "sale": 0,
        "views": 0
      },
      {
        "ad": 0,
        "adTotalCost": 0,
        "adTotalRoas": 0,
        "ad_revenue_ratio": 0,
        "ad_view_ratio": 0,
        "new_followers": 0,
        "partition_day": "2026-09-30",
        "revenue": 0,
        "sale": 0,
        "views": 0
      },
      {
        "ad": 0,
        "adTotalCost": 0,
        "adTotalRoas": 0,
        "ad_revenue_ratio": 0,
        "ad_view_ratio": 0,
        "new_followers": 0,
        "partition_day": "2026-10-01",
        "revenue": 0,
        "sale": 0,
        "views": 0
      }
    ],
    "dataEnd": "2026-10-28",
    "id": "7700682843906723103",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.daily`array
- `data.daily[].ad`integer
- `data.daily[].adTotalCost`integer
- `data.daily[].adTotalRoas`integer
- `data.daily[].ad_revenue_ratio`integer
- `data.daily[].ad_view_ratio`integer
- `data.daily[].new_followers`integer
- `data.daily[].partition_day`string
- `data.daily[].revenue`integer
- `data.daily[].sale`integer
- `data.daily[].views`integer
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Products sold through the video, with revenue](https://tokconnect.com/docs/api/videos/#get-videos-id-products)

`GET /v1/videos/{id}/products`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: products`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "products",
    "id": "7700682843906723103"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7700682843906723103/products" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/7700682843906723103/products", {
  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:

```json
{
  "data": {
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "7700682843906723103",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "products": [
      {
        "id": "1732268320365777584",
        "max_price": "$493.99",
        "min_price": "$493.99",
        "partition_day": "2026-10-29",
        "percentage": 100,
        "pri_cate_id": "Household Appliances",
        "product_title": "Shark PowerPro Flex Reveal Plus Cordless Vacuum - IZ382H",
        "revenue": 118627,
        "sale": 313,
        "sec_cate_id": "Home Appliances",
        "ter_cate_id": "Vacuums & Floor Care"
      }
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.products`array
- `data.products[].id`string
- `data.products[].max_price`string
- `data.products[].min_price`string
- `data.products[].partition_day`string
- `data.products[].percentage`integer
- `data.products[].pri_cate_id`string
- `data.products[].product_title`string
- `data.products[].revenue`integer
- `data.products[].sale`integer
- `data.products[].sec_cate_id`string
- `data.products[].ter_cate_id`string
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Revenue, units and ad metrics the video drove](https://tokconnect.com/docs/api/videos/#get-videos-id-sales)

`GET /v1/videos/{id}/sales`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: sales`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "sales",
    "id": "7700682843906723103"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7700682843906723103/sales" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/7700682843906723103/sales", {
  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:

```json
{
  "data": {
    "ads": {
      "ad2Cost": "$25.73k",
      "ad2Roas": 3.69,
      "ad_revenue_ratio": "80.00%",
      "ad_view_ratio": "28.88%",
      "video_id": "7700682843906723103"
    },
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "7700682843906723103",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totals": {
      "day_new_followers": "0",
      "day_revenue": "$3.95k",
      "day_sale": "10.43",
      "day_views": "76.7k",
      "new_followers": "0",
      "revenue": "$118.63k",
      "sale": "313",
      "video_id": "7700682843906723103",
      "views": "2.3m"
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.ads`object
- `data.ads.ad2Cost`string
- `data.ads.ad2Roas`number
- `data.ads.ad_revenue_ratio`string
- `data.ads.ad_view_ratio`string
- `data.ads.video_id`string
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.totals`object
- `data.totals.day_new_followers`string
- `data.totals.day_revenue`string
- `data.totals.day_sale`string
- `data.totals.day_views`string
- `data.totals.new_followers`string
- `data.totals.revenue`string
- `data.totals.sale`string
- `data.totals.video_id`string
- `data.totals.views`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Videos TikTok relates to this one](https://tokconnect.com/docs/api/videos/#get-videos-id-similar)

`GET /v1/videos/{id}/similar`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).
- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: similar`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "similar",
    "id": "7691522530129022221",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7691522530129022221/similar?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/videos/7691522530129022221/similar?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": false,
    "videos": [
      {
        "caption": "no need to overpluck your brows anymore 😌 this gel locks every hair in place and keeps them there all day",
        "comments": 26,
        "creator": {
          "followers": 2400000,
          "handle": "ingaterner",
          "id": "6915470077362865158",
          "nickname": "Inga Terner",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 11,
        "id": "7652228657624272141",
        "isAd": true,
        "language": "en",
        "likes": 4000,
        "posted": "2026-06-17T05:16:00Z",
        "products": [
          {
            "id": "1731195873060032840",
            "name": "The Brow Glue Crazy Lift, Brow",
            "sellerId": "7495306581925726536",
            "title": "The Brow Glue Crazy Lift, Brow Lamination Gel with 16HR Strong Hold & Built-In Styling Comb, NYX Professional Makeup"
          }
        ],
        "saves": 638,
        "shares": 109,
        "sound": {
          "author": "ky",
          "id": "7574176490877274935",
          "original": true,
          "title": "original sound"
        },
        "url": "https://www.tiktok.com/@ingaterner/video/7652228657624272141",
        "views": 137700
      },
      {
        "caption": "@MAC Cosmetics night",
        "comments": 7,
        "creator": {
          "followers": 2400000,
          "handle": "ingaterner",
          "id": "6915470077362865158",
          "nickname": "Inga Terner",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 10,
        "id": "7673769596033191182",
        "language": "en",
        "likes": 419,
        "posted": "2026-08-14T06:25:58Z",
        "saves": 31,
        "shares": 1,
        "sound": {
          "author": "Trendformusic",
          "id": "7532565244910308102",
          "original": true,
          "title": "son original"
        },
        "url": "https://www.tiktok.com/@ingaterner/video/7673769596033191182",
        "views": 8160
      },
      {
        "caption": "my go-to nude shades this summer",
        "comments": 11,
        "creator": {
          "followers": 2400000,
          "handle": "ingaterner",
          "id": "6915470077362865158",
          "nickname": "Inga Terner",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 15,
        "id": "7658093031144295693",
        "isAd": true,
        "language": "en",
        "likes": 403,
        "posted": "2026-07-03T00:32:32Z",
        "products": [
          {
            "id": "1729401426661773360",
            "name": "Lip Gloss",
            "sellerId": "7495171395322742832",
            "title": "Lip Gloss - High-Shine, Vanilla-Scented, Ultra Smooth Gloss with Luminous Finish Matte"
          }
        ],
        "saves": 101,
        "shares": 5,
        "sound": {
          "author": "burner.wave",
          "id": "7633979701119306510",
          "original": true,
          "title": "burner wave pour it up x all the way turnt up"
        },
        "url": "https://www.tiktok.com/@ingaterner/video/7658093031144295693",
        "views": 10100
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.followers`integer
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].durationSec`integer
- `data.videos[].id`string
- `data.videos[].isAd`boolean
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].products`array
- `data.videos[].products[].id`string
- `data.videos[].products[].name`string
- `data.videos[].products[].sellerId`string
- `data.videos[].products[].title`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.original`boolean
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [How similar videos performed](https://tokconnect.com/docs/api/videos/#get-videos-id-similar-revenue)

`GET /v1/videos/{id}/similar-revenue`

1 credit per call · Shop Analytics · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: similar_revenue`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "similar_revenue",
    "id": "7700682843906723103"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7700682843906723103/similar-revenue" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/7700682843906723103/similar-revenue", {
  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:

```json
{
  "data": {
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "7700682843906723103",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "similar": {
      "revenue": [
        {
          "ad": 1,
          "ai_video": 0,
          "content_type": "video",
          "create_time": "2026/10/21 19:35:52",
          "creator_id": "7408927728046933038",
          "description": "Which one do you think? #stickvacuum #petallergies #petparents #shark #sharkpowerproflex ",
          "duration": "1m 22s",
          "handle": "kid.shops",
          "id": "7699268904157334815",
          "music_title": "original sound - kid.shops",
          "original_duration": 81.834,
          "revenue": "$68.98k",
          "sale": 182,
          "views": "1.09m"
        },
        {
          "ad": 1,
          "ai_video": 0,
          "content_type": "video",
          "create_time": "2026/10/25 17:47:08",
          "creator_id": "7275090345011414059",
          "description": "Which cordless vacuum is better? What price they have this one at today you can’t beat it.. #vacuum #cordlessvacuum #stickvacuum #sharkvacuum #cleaning ",
          "duration": "1m 46s",
          "handle": "dealswithty",
          "id": "7700725240166436127",
          "music_title": "original sound",
          "original_duration": 106,
          "revenue": "$65.95k",
          "sale": 174,
          "views": "1.3m"
        },
        {
          "ad": 1,
          "ai_video": 0,
          "content_type": "video",
          "create_time": "2026/10/26 11:22:54",
          "creator_id": "7289195477476262958",
          "description": "Why pay more for a vacuum that does less… when you can pay less for one that does more?🤔 #vacuum #cleaning #petvacuum #sharkpowerproflexreveal ",
          "duration": "1m 34s",
          "handle": "ericsfindss",
          "id": "7700997310842490126",
          "music_title": "original sound",
          "original_duration": 94,
          "revenue": "$38.28k",
          "sale": 101,
          "views": "589.94k"
        }
      ],
      "type": "product"
    },
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.similar`object
- `data.similar.revenue`array
- `data.similar.revenue[].ad`integer
- `data.similar.revenue[].ai_video`integer
- `data.similar.revenue[].content_type`string
- `data.similar.revenue[].create_time`string
- `data.similar.revenue[].creator_id`string
- `data.similar.revenue[].description`string
- `data.similar.revenue[].duration`string
- `data.similar.revenue[].handle`string
- `data.similar.revenue[].id`string
- `data.similar.revenue[].music_title`string
- `data.similar.revenue[].original_duration`number
- `data.similar.revenue[].revenue`string
- `data.similar.revenue[].sale`integer
- `data.similar.revenue[].views`string
- `data.similar.type`string
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Existing captions as plain text (nothing is transcribed)](https://tokconnect.com/docs/api/videos/#get-videos-id-transcript)

`GET /v1/videos/{id}/transcript`

1 credit per call

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).

**1 more optional parameter**

- `language` (string): Preferred caption language, e.g. en.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: transcript`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "transcript",
    "id": "7691522530129022221"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7691522530129022221/transcript" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/7691522530129022221/transcript", {
  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 (this capture matched nothing):

```json
{
  "data": {
    "available": [],
    "message": "TikTok has no captions for this video, so there is no transcript. Nothing was transcribed or generated.",
    "noCaptions": true,
    "segments": [],
    "text": "",
    "video": {
      "authorUniqueId": "ingaterner",
      "desc": "the shiniest lips on the internet  @NOONI #noonipartner    #beauty #glitterlips #lipoil #kbeauty ",
      "durationMs": 18000,
      "id": "7691522530129022221",
      "playCount": 22632
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.available`array
- `data.message`string
- `data.noCaptions`boolean
- `data.segments`array
- `data.text`string
- `data.video`object
- `data.video.authorUniqueId`string
- `data.video.desc`string
- `data.video.durationMs`integer
- `data.video.id`string
- `data.video.playCount`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Replies to one comment (comment_id)](https://tokconnect.com/docs/api/videos/#get-videos-id-comments-comment-id-replies)

`GET /v1/videos/{id}/comments/{comment_id}/replies`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Video or photo post: a TikTok link (short vm./vt. links work), or the numeric post id (`videos[].id`).
- `comment_id` (string, path, required): The comment id from [`GET /v1/videos/{id}/comments`](https://tokconnect.com/docs/api/videos/#get-videos-id-comments).

**1 more optional parameter**

- `limit` (integer): Results per page. Max 50. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video` tool with `method: replies`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video",
  "arguments": {
    "method": "replies",
    "comment_id": "7701885045296956174",
    "id": "7691522530129022221"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/videos/7691522530129022221/comments/7701885045296956174/replies" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/7691522530129022221/comments/7701885045296956174/replies", {
  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 (this capture matched nothing):

```json
{
  "data": {
    "comments": [],
    "hasMore": false
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.comments`array
- `data.hasMore`boolean
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## TikTok feeds

Samples of TikTok's own feeds: For You (as a neutral US viewer), Explore categories, and Discover creators, hashtags and sounds. Samples, not rankings. Explore category ids come from [`GET /v1/reference/explore-categories`](https://tokconnect.com/docs/api/reference-lists/#get-reference-explore-categories).

### [Discover picks: creators, hashtags, sounds](https://tokconnect.com/docs/api/videos/#get-feeds-discover)

`GET /v1/feeds/discover`

1 credit per call · Paged

#### Parameters

- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `scene` (integer): Discover scene (15 is the full catalogue).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video_feed` tool with `method: discover`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video_feed",
  "arguments": {
    "method": "discover",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/feeds/discover?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/feeds/discover?${params}`, {
  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:

```json
{
  "data": {
    "creators": [
      {
        "followers": 74600000,
        "handle": "billieeilish",
        "id": "6879693940111901701",
        "nickname": "BILLIE EILISH",
        "secUid": "MS4wLjABAAAA…"
      },
      {
        "followers": 16900000,
        "handle": "rihanna",
        "id": "6621955904844021765",
        "nickname": "Rihanna",
        "secUid": "MS4wLjABAAAA…"
      },
      {
        "followers": 18100000,
        "handle": "edsheeran",
        "id": "173245838817808384",
        "nickname": "Ed Sheeran",
        "secUid": "MS4wLjABAAAA…"
      }
    ],
    "hashtags": [
      {
        "id": "7701142521555976205",
        "name": "tiktokshopcollectiblescarnivals",
        "views": 99200
      },
      {
        "id": "7029514091618123822",
        "name": "blackfridayearlyaccess",
        "views": 29800000
      },
      {
        "id": "1674571239209989",
        "name": "discoveryourgift",
        "views": 741000000
      }
    ],
    "sounds": [
      {
        "author": "3.1M videos",
        "id": "6740248251825391617",
        "title": "Forever (From \"Euphoria: Season 1\" Soundtrack)",
        "videos": 3100000
      },
      {
        "author": "87.1K videos",
        "id": "5000000001008467945",
        "title": "Quinceañera",
        "videos": 87100
      },
      {
        "author": "221.7K videos",
        "id": "222453230176251905",
        "title": "Hasta la Raíz",
        "videos": 221700
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.creators`array
- `data.creators[].followers`integer
- `data.creators[].handle`string
- `data.creators[].id`string
- `data.creators[].nickname`string
- `data.creators[].secUid`string
- `data.creators[].verified`boolean
- `data.hashtags`array
- `data.hashtags[].id`string
- `data.hashtags[].name`string
- `data.hashtags[].views`integer
- `data.sounds`array
- `data.sounds[].author`string
- `data.sounds[].id`string
- `data.sounds[].title`string
- `data.sounds[].videos`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Discover hashtags with sample videos](https://tokconnect.com/docs/api/videos/#get-feeds-discover-hashtags)

`GET /v1/feeds/discover/hashtags`

1 credit per call · Paged

#### Parameters

- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video_feed` tool with `method: discover_hashtags`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video_feed",
  "arguments": {
    "method": "discover_hashtags",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/feeds/discover/hashtags?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/feeds/discover/hashtags?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "hashtags": [
      {
        "description": "Try longer videos (videos longer than 1 minute)! Create longer videos to express yourself and share more of your story on TikTok",
        "id": "1604297750222853",
        "name": "longervideos",
        "sampleVideos": [
          {
            "caption": "Let’s Make a delicious fried Rice 😋👌🏽 Here is the recipe below 👇🏾  Ingredients  * 2 large chicken breast, cut into small cubes * 1/2 onion, diced  * 1/4 red, yellow and green bell peppers, diced * 3 Tbsp avocado oil  * 1 tsp crushed garlic…",
            "comments": 420,
            "creator": {
              "followers": 329100,
              "handle": "sifo_the_cooking_husband",
              "id": "6986275915727127557",
              "nickname": "The Cooking Husband- Foodie",
              "secUid": "MS4wLjABAAAA…"
            },
            "durationSec": 63,
            "hashtags": [
              {
                "id": "122788",
                "name": "friedrice"
              }
            ],
            "id": "7359831944349093125",
            "language": "en",
            "likes": 28300,
            "posted": "2024-04-20T06:26:53Z",
            "saves": 7996,
            "shares": 5047,
            "sound": {
              "author": "Deep Narratives & ZVRI & Culoe De Song",
              "id": "7259523870389045250",
              "title": "Insimbi"
            },
            "url": "https://www.tiktok.com/@sifo_the_cooking_husband/video/7359831944349093125",
            "views": 1200000
          }
        ],
        "url": "https://www.tiktok.com/tag/longervideos",
        "videos": 7654978,
        "views": 435009025218
      }
    ],
    "next": "eyJvZmZzZXQiOjJ9"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjJ9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.hashtags`array
- `data.hashtags[].id`string
- `data.hashtags[].name`string
- `data.hashtags[].sampleVideos`array
- `data.hashtags[].sampleVideos[].caption`string
- `data.hashtags[].sampleVideos[].comments`integer
- `data.hashtags[].sampleVideos[].creator`object
- `data.hashtags[].sampleVideos[].durationSec`integer
- `data.hashtags[].sampleVideos[].hashtags`array
- `data.hashtags[].sampleVideos[].id`string
- `data.hashtags[].sampleVideos[].language`string
- `data.hashtags[].sampleVideos[].likes`integer
- `data.hashtags[].sampleVideos[].posted`string
- `data.hashtags[].sampleVideos[].saves`integer
- `data.hashtags[].sampleVideos[].shares`integer
- `data.hashtags[].sampleVideos[].sound`object
- `data.hashtags[].sampleVideos[].url`string
- `data.hashtags[].sampleVideos[].views`integer
- `data.hashtags[].url`string
- `data.hashtags[].videos`integer
- `data.hashtags[].views`integer
- `data.next`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Videos from one Explore category](https://tokconnect.com/docs/api/videos/#get-feeds-explore)

`GET /v1/feeds/explore`

1 credit per call · Paged

#### Parameters

- `category_id` (integer): Id from [`GET /v1/reference/explore-categories`](https://tokconnect.com/docs/api/reference-lists/#get-reference-explore-categories).
- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video_feed` tool with `method: explore`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video_feed",
  "arguments": {
    "method": "explore",
    "category_id": 120,
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/feeds/explore?category_id=120&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  category_id: "120",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/feeds/explore?${params}`, {
  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:

```json
{
  "data": {
    "explore_item_source": "ug_same_country",
    "hasMore": true,
    "videos": [
      {
        "caption": "(✨️life changing title✨️)#kitten #why #confetti #weirdshithappenstome #whyandhowthefuckisthisconfettiflying",
        "comments": 12600,
        "creator": {
          "followers": 4315,
          "handle": "ech0d0gg",
          "id": "7609364764213527573",
          "nickname": "🌀//-Ech0._.D0gg-//🏳️‍⚧️",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 7,
        "hashtags": [
          {
            "id": "6845",
            "name": "kitten"
          },
          {
            "id": "7754",
            "name": "why"
          }
        ],
        "id": "7699977998820281620",
        "language": "en",
        "likes": 1100000,
        "place": {
          "id": "42203860546907036",
          "name": "Behind You"
        },
        "posted": "2026-10-23T21:27:25Z",
        "saves": 82300,
        "shares": 57100,
        "sound": {
          "author": "Jacket2026",
          "id": "7673220508500052756",
          "original": true,
          "title": "оригинальный звук"
        },
        "url": "https://www.tiktok.com/@ech0d0gg/video/7699977998820281620",
        "views": 9100000
      },
      {
        "caption": "тгк: lybima411    шота у нас не получился этот тренд",
        "comments": 2185,
        "creator": {
          "followers": 38200,
          "handle": "onlyfrantsss",
          "id": "6704968772954801158",
          "nickname": "onlyfrants",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 7,
        "id": "7699537178774359317",
        "language": "ru",
        "likes": 689900,
        "posted": "2026-10-22T16:56:43Z",
        "saves": 29700,
        "shares": 11100,
        "sound": {
          "author": "jamal",
          "id": "7687759421904096013",
          "original": true,
          "title": "original sound"
        },
        "url": "https://www.tiktok.com/@onlyfrantsss/video/7699537178774359317",
        "views": 9200000
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.explore_item_source`string
- `data.hasMore`boolean
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.followers`integer
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].durationSec`integer
- `data.videos[].hashtags`array
- `data.videos[].hashtags[].id`string
- `data.videos[].hashtags[].name`string
- `data.videos[].id`string
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].place`object
- `data.videos[].place.id`string
- `data.videos[].place.name`string
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.original`boolean
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [A page of the For You feed](https://tokconnect.com/docs/api/videos/#get-feeds-for-you)

`GET /v1/feeds/for-you`

1 credit per call · Paged

#### Parameters

- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video_feed` tool with `method: for_you`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video_feed",
  "arguments": {
    "method": "for_you",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/feeds/for-you?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/feeds/for-you?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "max_cursor": 7,
    "min_cursor": 0,
    "preload_awemes": null,
    "refresh_clear": 1,
    "videos": [
      {
        "caption": "7",
        "comments": 1,
        "creator": {
          "handle": "joyreelsshort.ca",
          "id": "7639195000521786388",
          "nickname": "JoyReelsshort CA",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 84.44,
        "id": "7700899193195449621",
        "language": "un",
        "likes": 330,
        "posted": "2026-10-26T13:02:30Z",
        "saves": 172,
        "shares": 13,
        "sound": {
          "author": "JoyReelsshort CA",
          "id": "7700899226716244757",
          "title": "suono originale - joyreelsshort.ca"
        },
        "url": "https://www.tiktok.com/@joyreelsshort.ca/video/7700899193195449621",
        "views": 58888
      },
      {
        "caption": "magari tornare a parigi",
        "comments": 1013,
        "creator": {
          "handle": "caterinamellusii",
          "id": "6696822421436253190",
          "nickname": "cate",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 10.634,
        "id": "7683308873704394016",
        "language": "it",
        "likes": 191772,
        "posted": "2026-09-08T23:22:41Z",
        "saves": 14604,
        "shares": 6840,
        "sound": {
          "author": "SoundWaves",
          "id": "7600964198817893142",
          "title": "suono originale - soundwaves.it"
        },
        "url": "https://www.tiktok.com/@caterinamellusii/video/7683308873704394016",
        "views": 1066264
      },
      {
        "caption": "Il carico è arrivato 🚛🪵 Faggio stagionato, pronto da bruciare. Fai scorta prima del freddo 🔥 Consegna a Lecco e in Brianza 📲 WhatsApp 320 746 7020 #legnadaardere #lecco #camino #stufaalegna #inverno",
        "comments": 10,
        "creator": {
          "handle": "radasnc",
          "id": "7047523516694217734",
          "nickname": "Rada",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 19.318,
        "hashtags": [
          {
            "id": "1663053011916806",
            "name": "legnadaardere"
          },
          {
            "id": "27958339",
            "name": "lecco"
          },
          {
            "id": "24299",
            "name": "camino"
          }
        ],
        "id": "7690872488833584417",
        "language": "it",
        "likes": 135,
        "posted": "2026-09-29T08:33:19Z",
        "saves": 37,
        "shares": 110,
        "sound": {
          "author": "🎧",
          "id": "7478091635340626710",
          "title": "suono originale - lyrics.7670"
        },
        "url": "https://www.tiktok.com/@radasnc/video/7690872488833584417",
        "views": 4172
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.max_cursor`integer
- `data.min_cursor`integer
- `data.preload_awemes`null
- `data.refresh_clear`integer
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].creator.verified`boolean
- `data.videos[].durationSec`number
- `data.videos[].id`string
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Comment giveaway draw

Draws random winners from a video's comments, with optional filters (`must_include`, unique users, exclude the creator). Set seed to make the draw reproducible and publish it so anyone can re-run it. The response says how many comments were eligible.

### [Comment giveaway draw](https://tokconnect.com/docs/api/videos/#post-videos-video-giveaway)

`POST /v1/videos/{video}/giveaway`

1 credit per call

#### Parameters

- `video` (string, path, required): Post id or full https://www.tiktok.com/@creator/video/<id> URL.

**7 more optional parameters**

- `detail` (string): full adds TikTok's raw payload (large). **Default**`compact` **One of** `compact` `full`.
- `exclude_creator` (boolean): Exclude comments by the video's creator. **Default**`true`.
- `max_comments` (integer): Comments to fetch, in pages of 50. **Default**`300`.
- `must_include` (string): Optional text a comment must contain (case-insensitive), e.g. a hashtag or keyword.
- `seed` (string): Optional seed for a reproducible draw. Publish it so anyone can re-run the draw.
- `unique_users` (boolean): Count each commenter once (their earliest fetched comment). **Default**`true`.
- `winners` (integer): How many winners to draw. **Default**`1`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `pick_comment_winners` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "pick_comment_winners",
  "arguments": {
    "id": "7691522530129022221"
  }
}
```

#### Request

```bash
curl -X POST "https://api.tokconnect.com/v1/videos/7691522530129022221/giveaway" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/videos/7691522530129022221/giveaway", {
  method: "POST",
  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:

```json
{
  "data": {
    "awemeId": "7691522530129022221",
    "coverage": 0.95,
    "eligible": 16,
    "excluded": {
      "duplicateUser": 3
    },
    "fairness": "Only the 19 fetched top-level comments were eligible; replies, hidden, filtered or deleted comments are not included. TikTok returns comments in its own order, so on large videos the fetched set is TikTok's selection, not a random sample…",
    "fetched": 19,
    "pages": 1,
    "random": "crypto/rand (not reproducible; pass seed for a verifiable draw)",
    "rules": {
      "creatorHandle": "ingaterner",
      "excludeCreator": true,
      "maxComments": 300,
      "mustInclude": "",
      "uniqueUsers": true,
      "winners": 1
    },
    "seed": null,
    "totalReported": 20,
    "winners": [
      {
        "authorNickname": "R.",
        "authorUniqueId": "r9079756",
        "createTime": 1791056562,
        "diggCount": 0,
        "id": "7692529272121000725",
        "isAuthor": false,
        "text": "😳😳😳"
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.awemeId`string
- `data.coverage`number
- `data.eligible`integer
- `data.excluded`object
- `data.excluded.duplicateUser`integer
- `data.fairness`string
- `data.fetched`integer
- `data.pages`integer
- `data.random`string
- `data.rules`object
- `data.rules.creatorHandle`string
- `data.rules.excludeCreator`boolean
- `data.rules.maxComments`integer
- `data.rules.mustInclude`string
- `data.rules.uniqueUsers`boolean
- `data.rules.winners`integer
- `data.seed`null
- `data.totalReported`integer
- `data.winners`array
- `data.winners[].authorNickname`string
- `data.winners[].authorUniqueId`string
- `data.winners[].createTime`integer
- `data.winners[].diggCount`integer
- `data.winners[].id`string
- `data.winners[].isAuthor`boolean
- `data.winners[].text`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/videos/

---

# TikTok LIVE API

One TikTok LIVE room: who is watching now, what it sold, and how the broadcast performed.

7 routes · 1 credit per call · Base URL https://api.tokconnect.com/v1 · [Shop Analytics data](https://tokconnect.com/tools/tiktok-shop-analytics/) · 17 markets

Call these routes with your own key, or ask the same question in plain words.

[Get an API key](https://app.tokconnect.com/api-key)[Ask about LIVE sales](https://app.tokconnect.com/?q=Which%20TikTok%20Shop%20LIVEs%20sold%20the%20most%20in%20the%20US%20this%20week%3F)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/lives/{id}`](https://tokconnect.com/docs/api/live/#get-lives-id) | Live status, viewers, likes, Shop selling |
| [GET `/v1/lives/{id}/history`](https://tokconnect.com/docs/api/live/#get-lives-id-history) | Performance over the broadcast |
| [GET `/v1/lives/{id}/sales`](https://tokconnect.com/docs/api/live/#get-lives-id-sales) | Revenue, units, duration, viewers |
| [GET `/v1/lives/{id}/strategy`](https://tokconnect.com/docs/api/live/#get-lives-id-strategy) | Sales mix of the broadcast, by category |
| [GET `/v1/lives/{id}/stream-urls`](https://tokconnect.com/docs/api/live/#get-lives-id-stream-urls) | Recording and stream URLs |
| [GET `/v1/lives/{id}/top-categories`](https://tokconnect.com/docs/api/live/#get-lives-id-top-categories) | Top categories sold |
| [GET `/v1/lives/{id}/products`](https://tokconnect.com/docs/api/live/#get-lives-id-products) | Products sold in the LIVE, with revenue |

## Common parameters

These read the same on the routes below that take them.

- `region` (string): Market as an ISO country code, default US. Amounts are in the market's currency. See [Markets](https://tokconnect.com/docs/api/markets/).
- `window` (string): Date range ending at the last complete day (about 2 days ago). Default 30d. Use start and end for a custom range. **One of** `7d` `30d` `90d` `180d` `365d`.
- `start` (string): Custom range start, YYYY-MM-DD.
- `end` (string): Custom range end, YYYY-MM-DD (capped at the last complete day).
- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## One TikTok LIVE

One LIVE room (id = room id from [`GET /v1/search/lives`](https://tokconnect.com/docs/api/search/#get-search-lives) or [`GET /v1/lives/top-selling`](https://tokconnect.com/docs/api/rankings/#get-lives-top-selling)).

- **Right now**: status, creator, viewers, likes, Shop selling.
- **Sales and history** (Shop Analytics, any market via region): revenue, units, duration, products, sales mix, top categories, recording links.

### [Live status, viewers, likes, Shop selling](https://tokconnect.com/docs/api/live/#get-lives-id)

`GET /v1/lives/{id}`

1 credit per call

#### Parameters

- `id` (string, path, required): LIVE room id.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `live` tool with `method: now`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "live",
  "arguments": {
    "method": "now",
    "id": "7702601891041020685"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/lives/7702601891041020685" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/lives/7702601891041020685", {
  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:

```json
{
  "data": {
    "creator": {
      "handle": "creator_1",
      "id": "6959222640256353285",
      "nickname": "Example creator 1",
      "secUid": "MS4wLjABAAAA…"
    },
    "likes": 9898,
    "live": true,
    "roomId": "7702601891041020685",
    "started": "2026-10-30T23:10:19Z",
    "totalViewers": 8213,
    "url": "https://www.tiktok.com/@creator_1/live",
    "viewers": 1428
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.creator`object
- `data.creator.handle`string
- `data.creator.id`string
- `data.creator.nickname`string
- `data.creator.secUid`string
- `data.likes`integer
- `data.live`boolean
- `data.roomId`string
- `data.started`string
- `data.title`string
- `data.totalViewers`integer
- `data.url`string
- `data.viewers`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Performance over the broadcast](https://tokconnect.com/docs/api/live/#get-lives-id-history)

`GET /v1/lives/{id}/history`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): LIVE room id.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `live` tool with `method: history`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "live",
  "arguments": {
    "method": "history",
    "id": "7699061230417349407"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/lives/7699061230417349407/history" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/lives/7699061230417349407/history", {
  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:

```json
{
  "data": {
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "history": [
      {
        "duration": "0",
        "finish_time": "1792579235",
        "revenue": "0.0",
        "total_user": "6621",
        "total_user_incre": "0",
        "viewer_num": "350"
      },
      {
        "duration": "0",
        "finish_time": "1792579538",
        "revenue": "86.8559709094514",
        "total_user": "8144",
        "total_user_incre": "1523",
        "viewer_num": "410"
      },
      {
        "duration": "0",
        "finish_time": "1792579835",
        "revenue": "82.69281537669372",
        "total_user": "9594",
        "total_user_incre": "1450",
        "viewer_num": "438"
      }
    ],
    "id": "7699061230417349407",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.dataEnd`string
- `data.history`array
- `data.history[].duration`string
- `data.history[].finish_time`string
- `data.history[].revenue`string
- `data.history[].total_user`string
- `data.history[].total_user_incre`string
- `data.history[].viewer_num`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Revenue, units, duration, viewers](https://tokconnect.com/docs/api/live/#get-lives-id-sales)

`GET /v1/lives/{id}/sales`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): LIVE room id.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `live` tool with `method: sales`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "live",
  "arguments": {
    "method": "sales",
    "id": "7699061230417349407"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/lives/7699061230417349407/sales" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/lives/7699061230417349407/sales", {
  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:

```json
{
  "data": {
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "7699061230417349407",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "totals": {
      "id": "7699061230417349407",
      "revenue": "$174.88k",
      "sale": "5.87k",
      "unit_price": "$29.81",
      "viewer_num": "435",
      "views": "3.09m"
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.totals`object
- `data.totals.id`string
- `data.totals.revenue`string
- `data.totals.sale`string
- `data.totals.unit_price`string
- `data.totals.viewer_num`string
- `data.totals.views`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Sales mix of the broadcast, by category](https://tokconnect.com/docs/api/live/#get-lives-id-strategy)

`GET /v1/lives/{id}/strategy`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): LIVE room id.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `live` tool with `method: strategy`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "live",
  "arguments": {
    "method": "strategy",
    "id": "7699061230417349407"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/lives/7699061230417349407/strategy" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/lives/7699061230417349407/strategy", {
  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:

```json
{
  "data": {
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "7699061230417349407",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "pricing": [
      {
        "cate_id": "Others",
        "id": "-1",
        "percentage": "100",
        "revenue": "$174.88k"
      },
      {
        "cate_id": "Beauty & Personal Care",
        "id": "601450",
        "percentage": 92,
        "revenue": "$161.70k"
      },
      {
        "cate_id": "Home Supplies",
        "id": "600001",
        "percentage": 0,
        "revenue": "$0.00"
      }
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.pricing`array
- `data.pricing[].cate_id`string
- `data.pricing[].id`string
- `data.pricing[].percentage`string
- `data.pricing[].revenue`string
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Recording and stream URLs](https://tokconnect.com/docs/api/live/#get-lives-id-stream-urls)

`GET /v1/lives/{id}/stream-urls`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): LIVE room id.
- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `live` tool with `method: stream_urls`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "live",
  "arguments": {
    "method": "stream_urls",
    "id": "7702601891041020685",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/lives/7702601891041020685/stream-urls?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/lives/7702601891041020685/stream-urls",
    params={
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/lives/7702601891041020685/stream-urls?${params}`, {
  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:

```json
{
  "data": {
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "7702601891041020685",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "urls": {
      "is_purchase": false,
      "record_type": "SHORT",
      "screenshotUrl": "(signed media URL)",
      "shortUrl": "(signed media URL)"
    },
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.urls`object
- `data.urls.is_purchase`boolean
- `data.urls.record_type`string
- `data.urls.screenshotUrl`string
- `data.urls.shortUrl`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Top categories sold](https://tokconnect.com/docs/api/live/#get-lives-id-top-categories)

`GET /v1/lives/{id}/top-categories`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): LIVE room id.

**1 more optional parameter**

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `live` tool with `method: top_categories`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "live",
  "arguments": {
    "method": "top_categories",
    "id": "7699061230417349407"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/lives/7699061230417349407/top-categories" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/lives/7699061230417349407/top-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:

```json
{
  "data": {
    "categories": {
      "topCates": [
        {
          "cate_id": "Beauty & Personal Care",
          "id": "601450",
          "revenue": 5030
        }
      ]
    },
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "id": "7699061230417349407",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.categories`object
- `data.categories.topCates`array
- `data.categories.topCates[].cate_id`string
- `data.categories.topCates[].id`string
- `data.categories.topCates[].revenue`integer
- `data.currency`string
- `data.dataEnd`string
- `data.id`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Products sold in the LIVE, with revenue](https://tokconnect.com/docs/api/live/#get-lives-id-products)

`GET /v1/lives/{id}/products`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): LIVE room id.
- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `live` tool with `method: products`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "live",
  "arguments": {
    "method": "products",
    "id": "7702601891041020685",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/lives/7702601891041020685/products?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/lives/7702601891041020685/products?${params}`, {
  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 (this capture matched nothing):

```json
{
  "data": {
    "count": 0,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "hasMore": false,
    "id": "7702601891041020685",
    "items": [],
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.hasMore`boolean
- `data.id`string
- `data.items`array
- `data.market`string
- `data.notes`array
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/live/

---

# TikTok search API

Search TikTok the way the app answers right now: videos, photo posts, accounts, hashtags, LIVE rooms and places.

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

Call these routes with your own key.

[Get an API key](https://app.tokconnect.com/api-key)[No code? Try the free video finder](https://tokconnect.com/tools/tiktok-video-finder/)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/search/videos`](https://tokconnect.com/docs/api/search/#get-search-videos) | Video posts |
| [GET `/v1/search/photos`](https://tokconnect.com/docs/api/search/#get-search-photos) | Photo carousel posts |
| [GET `/v1/search/top`](https://tokconnect.com/docs/api/search/#get-search-top) | Mixed results in one call (often empty; use videos, photos or accounts) |
| [GET `/v1/search/creators`](https://tokconnect.com/docs/api/search/#get-search-creators) | Accounts matching keyword |
| [GET `/v1/search/hashtags`](https://tokconnect.com/docs/api/search/#get-search-hashtags) | Hashtags matching keyword |
| [GET `/v1/search/lives`](https://tokconnect.com/docs/api/search/#get-search-lives) | LIVE rooms matching keyword |
| [GET `/v1/search/places`](https://tokconnect.com/docs/api/search/#get-search-places) | Businesses, venues and landmarks matching keyword |

## Common parameters

These read the same on the routes below that take them.

- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## Search TikTok videos

Search TikTok posts by keyword, as TikTok's own search returns them now: views, likes, comments, shares, saves, creator, hashtags, sound and linked Shop products. Not a sales ranking (use [Rankings](https://tokconnect.com/docs/api/rankings/)). Search sounds is on the [sounds page](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-search-sounds).

### [Video posts](https://tokconnect.com/docs/api/search/#get-search-videos)

`GET /v1/search/videos`

1 credit per call · Paged · 17 markets

#### Parameters

- `keyword` (string, required): Search phrase, e.g. 'lip oil'.
- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

**3 more optional parameters**

- `date` (string): Only posts from this window (default any). **One of** `any` `day` `week` `month` `half_year`.
- `region` (string): Market as an ISO country code, default US. Amounts are in the market's currency. See [Markets](https://tokconnect.com/docs/api/markets/).
- `sort` (string): Relevance (default), `most_liked` or newest. **One of** `relevance` `most_liked` `newest`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video_search` tool with `method: videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video_search",
  "arguments": {
    "method": "videos",
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/search/videos?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/search/videos",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/search/videos?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJvZmZzZXQiOjMsInNlYXJjaF9pZCI6InUuMjAyNjEwMzAyMzI2MjBEQTUwODYxOTJERDYwMjNENTg2NSJ9",
    "videos": [
      {
        "caption": "the shiniest lips on the internet  @NOONI #noonipartner    #beauty #glitterlips #lipoil #kbeauty",
        "comments": 20,
        "creator": {
          "followers": 2415482,
          "handle": "ingaterner",
          "id": "6915470077362865158",
          "nickname": "Inga Terner",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 18.067,
        "hashtags": [
          {
            "id": "7305074851570516011",
            "name": "noonipartner"
          },
          {
            "id": "5393",
            "name": "beauty"
          }
        ],
        "id": "7691522530129022221",
        "language": "en",
        "likes": 1049,
        "posted": "2026-10-01T02:36:03Z",
        "saves": 207,
        "shares": 39,
        "sound": {
          "author": "JERI",
          "id": "7139362230881094442",
          "original": true,
          "title": "ariana grande . ill do it"
        },
        "url": "https://www.tiktok.com/@ingaterner/video/7691522530129022221",
        "views": 22632
      },
      {
        "caption": "Fall lip oil check! The color, the shine, the vibes. #FallLipOil #FallMakeup #AutumnBeauty #LipOil #GlossyLips",
        "comments": 24,
        "creator": {
          "followers": 1330988,
          "handle": "hannah_tyre27",
          "id": "6944438159117157381",
          "nickname": "🩷Hannah Tyre 🩷",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 51.667,
        "hashtags": [
          {
            "id": "7151573380594925611",
            "name": "falllipoil"
          },
          {
            "id": "739483",
            "name": "fallmakeup"
          }
        ],
        "id": "7699874217633828110",
        "language": "en",
        "likes": 549,
        "posted": "2026-10-23T14:45:09Z",
        "saves": 30,
        "shares": 22,
        "sound": {
          "author": "🩷Hannah Tyre 🩷",
          "id": "7699874343160974094",
          "original": true,
          "title": "original sound - hannah_tyre27"
        },
        "url": "https://www.tiktok.com/@hannah_tyre27/video/7699874217633828110",
        "views": 5107
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjMsInNlYXJjaF9pZCI6InUuMjAyNjEwMzAyMzI2MjBEQTUwODYxOTJERDYwMjNENTg2NSJ9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.followers`integer
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].durationSec`number
- `data.videos[].hashtags`array
- `data.videos[].hashtags[].id`string
- `data.videos[].hashtags[].name`string
- `data.videos[].id`string
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.original`boolean
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Photo carousel posts](https://tokconnect.com/docs/api/search/#get-search-photos)

`GET /v1/search/photos`

1 credit per call · Paged

#### Parameters

- `keyword` (string, required): Search phrase, e.g. 'lip oil'.
- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video_search` tool with `method: photos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video_search",
  "arguments": {
    "method": "photos",
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/search/photos?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/search/photos",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/search/photos?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJvZmZzZXQiOjMsInNlYXJjaF9pZCI6InUudy4yMDI2MTAzMDIzMjYyMkJFMkJDQkVDOTVFRTY4MkVEQzJEIn0",
    "search_id": "u.w.20261030232622BE2BCBEC95EE682EDC2D",
    "videos": [
      {
        "caption": "What’s your favorite lip oil? Comment below! 👇 💋 Top 10 Lip Oils 🥇 Clarins Lip Comfort Oil * Nourishes & hydrates * Non-sticky * Glossy finish * Comfortable all-day wear 🥈 Dior Addict Lip Glow Oil * Hydrating * High-shine finish *…",
        "comments": 3,
        "creator": {
          "followers": 60,
          "handle": "glow4girlz",
          "id": "7629889741245269006",
          "nickname": "glow4girlz",
          "secUid": "MS4wLjABAAAA…"
        },
        "hashtags": [
          {
            "id": "5391",
            "name": "makeup"
          },
          {
            "id": "44367",
            "name": "top10"
          }
        ],
        "id": "7670279717978737933",
        "imageCount": 1,
        "language": "en",
        "likes": 314,
        "photoPost": true,
        "posted": "2026-08-04T20:43:07Z",
        "saves": 171,
        "shares": 35,
        "sound": {
          "author": "Doja Cat",
          "id": "6976278887063898114",
          "title": "Woman"
        },
        "url": "https://www.tiktok.com/@glow4girlz/photo/7670279717978737933",
        "views": 44000
      },
      {
        "caption": "No one talks about these lip oils!! Romand makes such glossy and juicy lippies #romand #kbeauty #lipoil #lipgloss #juicy",
        "comments": 18,
        "creator": {
          "followers": 95300,
          "handle": "beansforfun",
          "id": "6754991130918142978",
          "nickname": "Jeslyn | Beansforfun",
          "secUid": "MS4wLjABAAAA…"
        },
        "hashtags": [
          {
            "id": "16975188",
            "name": "romand"
          },
          {
            "id": "1589191",
            "name": "kbeauty"
          }
        ],
        "id": "7670927766337981704",
        "imageCount": 6,
        "language": "en",
        "likes": 2853,
        "photoPost": true,
        "posted": "2026-08-06T14:37:37Z",
        "saves": 712,
        "shares": 140,
        "sound": {
          "author": "m.i.n.d.i07",
          "id": "7545216806445763329",
          "original": true,
          "title": "original sound"
        },
        "url": "https://www.tiktok.com/@beansforfun/photo/7670927766337981704",
        "views": 61600
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjMsInNlYXJjaF9pZCI6InUudy4yMDI2MTAzMDIzMjYyMkJFMkJDQkVDOTVFRTY4MkVEQzJEIn0"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.search_id`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.followers`integer
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].hashtags`array
- `data.videos[].hashtags[].id`string
- `data.videos[].hashtags[].name`string
- `data.videos[].id`string
- `data.videos[].imageCount`integer
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].photoPost`boolean
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Mixed results in one call (often empty; use videos, photos or accounts)](https://tokconnect.com/docs/api/search/#get-search-top)

`GET /v1/search/top`

1 credit per call · Paged

#### Parameters

- `keyword` (string, required): Search phrase, e.g. 'lip oil'.
- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `video_search` tool with `method: all`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "video_search",
  "arguments": {
    "method": "all",
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/search/top?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/search/top",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/search/top?${params}`, {
  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:

```json
{
  "data": {
    "cursor": 10,
    "data": [
      {
        "aweme_info": {
          "caption": "the shiniest lips on the internet  @NOONI #noonipartner    #beauty #glitterlips #lipoil #kbeauty",
          "comments": 20,
          "creator": {
            "followers": 2414965,
            "handle": "ingaterner",
            "id": "6915470077362865158",
            "nickname": "Inga Terner",
            "secUid": "MS4wLjABAAAA…"
          },
          "durationSec": 18.067,
          "hashtags": [
            {
              "id": "7305074851570516011",
              "name": "noonipartner"
            }
          ],
          "id": "7691522530129022221",
          "language": "en",
          "likes": 1049,
          "posted": "2026-10-01T02:36:03Z",
          "saves": 207,
          "shares": 39,
          "sound": {
            "author": "JERI",
            "id": "7139362230881094442",
            "original": true,
            "title": "ariana grande . ill do it"
          },
          "url": "https://www.tiktok.com/@ingaterner/video/7691522530129022221",
          "views": 22632
        },
        "card_profile": {},
        "doc_id": 7691522530129022000,
        "doc_type": 183,
        "feedback_type": "video",
        "preload_img": {
          "urls": [
            "https://…/image.webp"
          ]
        },
        "provider_doc_id_str": "7691522530129022221",
        "search_aweme_info": {
          "has_creation_intention": false
        },
        "type": 1
      }
    ],
    "has_more": true,
    "headers": [],
    "prefer_layout": "double_column",
    "qc": "",
    "result_status": 4,
    "search_id": "u.20261030232623A68179925CD016394128",
    "version": "v1"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.cursor`integer
- `data.data`array
- `data.data[].aweme_info`object
- `data.data[].aweme_info.caption`string
- `data.data[].aweme_info.comments`integer
- `data.data[].aweme_info.creator`object
- `data.data[].aweme_info.creator.followers`integer
- `data.data[].aweme_info.creator.handle`string
- `data.data[].aweme_info.creator.id`string
- `data.data[].aweme_info.creator.nickname`string
- `data.data[].aweme_info.creator.secUid`string
- `data.data[].aweme_info.durationSec`number
- `data.data[].aweme_info.hashtags`array
- `data.data[].aweme_info.id`string
- `data.data[].aweme_info.language`string
- `data.data[].aweme_info.likes`integer
- `data.data[].aweme_info.posted`string
- `data.data[].aweme_info.saves`integer
- `data.data[].aweme_info.shares`integer
- `data.data[].aweme_info.sound`object
- `data.data[].aweme_info.sound.author`string
- `data.data[].aweme_info.sound.id`string
- `data.data[].aweme_info.sound.original`boolean
- `data.data[].aweme_info.sound.title`string
- `data.data[].aweme_info.url`string
- `data.data[].aweme_info.views`integer
- `data.data[].card_profile`object
- `data.data[].doc_id`integer
- `data.data[].doc_type`integer
- `data.data[].feedback_type`string
- `data.data[].preload_img`object
- `data.data[].preload_img.urls`array
- `data.data[].provider_doc_id_str`string
- `data.data[].search_aweme_info`object
- `data.data[].search_aweme_info.has_creation_intention`boolean
- `data.data[].type`integer
- `data.has_more`boolean
- `data.headers`array
- `data.prefer_layout`string
- `data.qc`string
- `data.result_status`integer
- `data.search_id`string
- `data.version`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Search TikTok accounts

Search TikTok accounts by keyword (name, handle or niche), as TikTok's account search returns them now, with follower bounds, verified-only and sorting applied to the page. Not a sales ranking: use [`GET /v1/affiliates/top`](https://tokconnect.com/docs/api/rankings/#get-affiliates-top).

### [Accounts matching keyword](https://tokconnect.com/docs/api/search/#get-search-creators)

`GET /v1/search/creators`

1 credit per call · Paged

#### Parameters

- `keyword` (string, required): Search phrase, e.g. 'lip oil'.
- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

**4 more optional parameters**

- `max_followers` (integer): Maximum followers. 0 = none.
- `min_followers` (integer): Minimum followers. 0 = none.
- `sort` (string): relevance (default), followers or likes. **One of** `relevance` `followers` `likes`.
- `verified_only` (boolean): Keep only verified accounts. **Default**`false`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creator_search` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creator_search",
  "arguments": {
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/search/creators?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/search/creators",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/search/creators?${params}`, {
  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:

```json
{
  "data": {
    "creators": [
      {
        "followers": 54911,
        "following": 28,
        "handle": "lipoil417",
        "id": "6865315608574854146",
        "likes": 472040,
        "nickname": "ลิปออยฮัปเตงงง(55K)🌷",
        "secUid": "MS4wLjABAAAA…",
        "url": "https://www.tiktok.com/@lipoil417",
        "videos": 186
      },
      {
        "followers": 499138,
        "following": 311,
        "handle": "eb.bahboh",
        "id": "6825796908113150981",
        "likes": 18588205,
        "nickname": "เต๋าชอบทาLip Oil Everyskin",
        "secUid": "MS4wLjABAAAA…",
        "url": "https://www.tiktok.com/@eb.bahboh",
        "videos": 1654
      },
      {
        "followers": 642,
        "following": 591,
        "handle": "mylipoil",
        "id": "6641452638477697025",
        "likes": 22168,
        "nickname": "♡Lip oil♡",
        "secUid": "MS4wLjABAAAA…",
        "url": "https://www.tiktok.com/@mylipoil",
        "videos": 47
      }
    ],
    "hasMore": true,
    "next": "eyJjdXJzb3IiOjMsInNlYXJjaF9pZCI6InUuMjAyNjEwMzAyMzI2MzVFNjRGQ0MzRkM5NTc3RkEzOUQyNCJ9",
    "retrievedCount": 3
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOjMsInNlYXJjaF9pZCI6InUuMjAyNjEwMzAyMzI2MzVFNjRGQ0MzRkM5NTc3RkEzOUQyNCJ9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.creators`array
- `data.creators[].followers`integer
- `data.creators[].following`integer
- `data.creators[].handle`string
- `data.creators[].id`string
- `data.creators[].likes`integer
- `data.creators[].nickname`string
- `data.creators[].secUid`string
- `data.creators[].url`string
- `data.creators[].verified`boolean
- `data.creators[].videos`integer
- `data.hasMore`boolean
- `data.next`string
- `data.retrievedCount`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Find hashtags

Find hashtags by keyword, with total views and video counts for each. Pass a hashtag's id to the hashtag routes for its videos and related tags.

### [Hashtags matching keyword](https://tokconnect.com/docs/api/search/#get-search-hashtags)

`GET /v1/search/hashtags`

1 credit per call · Paged

#### Parameters

- `keyword` (string, required): Search phrase, e.g. 'lip oil'.
- `limit` (integer): Results per page. Max 50. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `hashtag_search` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "hashtag_search",
  "arguments": {
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/search/hashtags?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/search/hashtags",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/search/hashtags?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "hashtags": [
      {
        "id": "19957680",
        "name": "lipoil",
        "url": "https://www.tiktok.com/tag/lipoil",
        "videos": 788416,
        "views": 11473297599
      },
      {
        "id": "1643439800933382",
        "name": "lipoils",
        "url": "https://www.tiktok.com/tag/lipoils",
        "videos": 77196,
        "views": 1105123774
      },
      {
        "id": "1676866847720454",
        "name": "lipoil💋",
        "url": "https://www.tiktok.com/tag/lipoil💋",
        "videos": 649,
        "views": 4702098
      }
    ],
    "next": "eyJjdXJzb3IiOjMsInNlYXJjaF9pZCI6InUuMjAyNjEwMzAyMzI2NTVCMzMwODE0MjE0MDBGOTg2ODY0RSJ9"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOjMsInNlYXJjaF9pZCI6InUuMjAyNjEwMzAyMzI2NTVCMzMwODE0MjE0MDBGOTg2ODY0RSJ9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.hashtags`array
- `data.hashtags[].id`string
- `data.hashtags[].name`string
- `data.hashtags[].url`string
- `data.hashtags[].videos`integer
- `data.hashtags[].views`integer
- `data.next`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Search LIVE now

Find TikTok LIVE broadcasts on now by keyword, with viewers and whether the room sells Shop products. Pass a room id to the LIVE routes. Not a sales ranking (use [`GET /v1/lives/top-selling`](https://tokconnect.com/docs/api/rankings/#get-lives-top-selling)).

### [LIVE rooms matching keyword](https://tokconnect.com/docs/api/search/#get-search-lives)

`GET /v1/search/lives`

1 credit per call · Paged · 17 markets

#### Parameters

- `keyword` (string, required): Search phrase, e.g. 'lip oil'.
- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `region` (string): Market as an ISO country code, default US. Amounts are in the market's currency. See [Markets](https://tokconnect.com/docs/api/markets/).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `live_search` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "live_search",
  "arguments": {
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/search/lives?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/search/lives",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/search/lives?${params}`, {
  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:

```json
{
  "data": {
    "feedback_type": "live",
    "guide_search_words": null,
    "hasMore": false,
    "rooms": [
      {
        "creator": {
          "handle": "mirthandmayhemapothecary",
          "id": "6674289300136510470",
          "nickname": "Mae✨Mirth & Mayhem Apothecary✨",
          "secUid": "MS4wLjABAAAA…"
        },
        "likes": 1805,
        "live": true,
        "roomId": "7702602665781005070",
        "started": "2026-10-30T23:13:34Z",
        "title": "Lip gloss and jewelry!",
        "url": "https://www.tiktok.com/@creator_1/live",
        "viewers": 14
      },
      {
        "creator": {
          "handle": "maknzperfumes",
          "id": "7281875170079638571",
          "nickname": "MAKNZ",
          "secUid": "MS4wLjABAAAA…"
        },
        "likes": 5415,
        "live": true,
        "roomId": "7702558024967899918",
        "shopping": true,
        "started": "2026-10-30T20:20:38Z",
        "title": "OIL BASED BY JASMINE",
        "url": "https://www.tiktok.com/@creator_1/live",
        "viewers": 5
      },
      {
        "creator": {
          "handle": "drixelyyy",
          "id": "6780994045612229637",
          "nickname": "Dri•xely🌺🫧",
          "secUid": "MS4wLjABAAAA…"
        },
        "likes": 7712,
        "live": true,
        "roomId": "7702596084547259149",
        "shopping": true,
        "started": "2026-10-30T22:48:00Z",
        "title": "🚨DIFFUSER OIL RESTOCK 🥰‼️",
        "url": "https://www.tiktok.com/@creator_1/live",
        "viewers": 6
      }
    ],
    "search_id": "u.2026103023270001AF2C7F8351C72F0BE1",
    "version": "v2"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.feedback_type`string
- `data.guide_search_words`null
- `data.hasMore`boolean
- `data.rooms`array
- `data.rooms[].creator`object
- `data.rooms[].creator.handle`string
- `data.rooms[].creator.id`string
- `data.rooms[].creator.nickname`string
- `data.rooms[].creator.secUid`string
- `data.rooms[].likes`integer
- `data.rooms[].live`boolean
- `data.rooms[].roomId`string
- `data.rooms[].started`string
- `data.rooms[].title`string
- `data.rooms[].url`string
- `data.rooms[].viewers`integer
- `data.search_id`string
- `data.version`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Search places

Finds businesses, venues and landmarks tagged on TikTok by keyword, with address, category and tagged video count. Pass a place id to the place routes for details, videos or reviews.

### [Businesses, venues and landmarks matching keyword](https://tokconnect.com/docs/api/search/#get-search-places)

`GET /v1/search/places`

1 credit per call

#### Parameters

- `keyword` (string, required): Place or business term, e.g. 'coffee shop'.

**2 more optional parameters**

- `count` (integer): Places per page. **Default**`10`.
- `detail` (string): full adds TikTok's raw payload (large). **Default**`compact` **One of** `compact` `full`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `place_search` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "place_search",
  "arguments": {
    "keyword": "lip oil"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/search/places?keyword=lip%20oil" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
});
const res = await fetch(`https://api.tokconnect.com/v1/search/places?${params}`, {
  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:

```json
{
  "data": {
    "places": [
      {
        "address": "3939 S Interstate 35, San Marcos, United States",
        "category": "Beauty Salon",
        "country": "US",
        "id": "20319181072627620",
        "lat": 29.831224,
        "lng": -97.983594,
        "name": "Clarins",
        "url": "https://www.tiktok.com/place/-20319181072627620",
        "videos": 1
      },
      {
        "address": "4620 71st St #30, Lubbock, TX 79424, USA",
        "category": "Hair Salon",
        "country": "US",
        "hours": "09:00 - 18:00",
        "id": "21568226335734203",
        "lat": 33.529574,
        "lng": -101.911819,
        "name": "Glam LAB",
        "tags": [
          "Boho Braids",
          "Braids Specialist",
          "Locks Styling"
        ],
        "url": "https://www.tiktok.com/place/-21568226335734203",
        "videos": 21
      },
      {
        "address": "Vicinale Saguerra 998, 74020 Taranto, Italy",
        "country": "IT",
        "id": "21568226329628837",
        "lat": 40.36815,
        "lng": 17.330194,
        "name": "Imoil",
        "url": "https://www.tiktok.com/place/-21568226329628837"
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.places`array
- `data.places[].address`string
- `data.places[].category`string
- `data.places[].country`string
- `data.places[].id`string
- `data.places[].lat`number
- `data.places[].lng`number
- `data.places[].name`string
- `data.places[].url`string
- `data.places[].videos`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/search/

---

# TikTok keyword and search demand API

What people search for on TikTok, from TikTok's own Creator Search Insights, plus autocomplete and keyword ideas from TikTok and TikTok Shop.

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

Call these routes with your own key, or ask the same question in plain words. Not a developer? Try the free [TikTok keyword research tool](https://tokconnect.com/tools/tiktok-keyword-research/) or ask in the research agent.

[Get an API key](https://app.tokconnect.com/api-key)[Ask what people search](https://app.tokconnect.com/?q=What%20are%20people%20searching%20on%20TikTok%20about%20protein%20snacks%2C%20and%20where%20is%20there%20little%20content%3F)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/searches`](https://tokconnect.com/docs/api/demand/#get-searches) | Topics matching keyword |
| [GET `/v1/searches/feed`](https://tokconnect.com/docs/api/demand/#get-searches-feed) | A ready-made list (channel) |
| [GET `/v1/searches/trending`](https://tokconnect.com/docs/api/demand/#get-searches-trending) | Trending searches, optionally by category |
| [GET `/v1/searches/{id}`](https://tokconnect.com/docs/api/demand/#get-searches-id) | searchVolume, trend, category, top countries |
| [GET `/v1/searches/{id}/audience`](https://tokconnect.com/docs/api/demand/#get-searches-id-audience) | Age, gender and location of searchers |
| [GET `/v1/searches/{id}/guidance`](https://tokconnect.com/docs/api/demand/#get-searches-id-guidance) | TikTok's suggested hooks, hashtags and outlines (often unavailable) |
| [GET `/v1/searches/{id}/popularity`](https://tokconnect.com/docs/api/demand/#get-searches-id-popularity) | Daily popularity chart, worldwide or per country |
| [GET `/v1/searches/{id}/related`](https://tokconnect.com/docs/api/demand/#get-searches-id-related) | Related searches with their searchVolume |
| [GET `/v1/searches/{id}/videos`](https://tokconnect.com/docs/api/demand/#get-searches-id-videos) | Videos TikTok shows for the topic |
| [GET `/v1/searches/{id}/related-queries`](https://tokconnect.com/docs/api/demand/#get-searches-id-related-queries) | Follow-up searches TikTok links to it |
| [GET `/v1/keywords/accounts`](https://tokconnect.com/docs/api/demand/#get-keywords-accounts) | Account (@handle) suggestions |
| [GET `/v1/keywords/shop`](https://tokconnect.com/docs/api/demand/#get-keywords-shop) | TikTok Shop search autocomplete |
| [GET `/v1/keywords/signals`](https://tokconnect.com/docs/api/demand/#get-keywords-signals) | Autocomplete with click-through and shopping-intent signals |
| [GET `/v1/keywords/suggest`](https://tokconnect.com/docs/api/demand/#get-keywords-suggest) | TikTok search autocomplete |
| [GET `/v1/keywords/trending`](https://tokconnect.com/docs/api/demand/#get-keywords-trending) | Trending phrases TikTok's website shows |
| [GET `/v1/keywords/ad-library`](https://tokconnect.com/docs/api/demand/#get-keywords-ad-library) | EU/UK Ad Library advertiser and keyword autocomplete |

## Common parameters

These read the same on the routes below that take them.

- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## Find TikTok search topics

Find what people search on TikTok and where demand outruns content (Creator Search Insights). `searchVolume` is TikTok's 7-day popularity figure, never a monthly count; `videoCount` 0 marks a content gap. Each topic also has a `queryId` and a daily trend.

Use it for demand, content gaps and trend research. Pass a topic's queryId to the routes under [`GET /v1/searches/{id}`](https://tokconnect.com/docs/api/demand/#get-searches-id) for charts, audience and related searches. Looking for live search results? See [Search](https://tokconnect.com/docs/api/search/).

### [Topics matching keyword](https://tokconnect.com/docs/api/demand/#get-searches)

`GET /v1/searches`

1 credit per call · Paged

#### Parameters

- `keyword` (string): Phrase to match, e.g. 'bicep workouts'.
- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `language` (string): Language code from [`GET /v1/reference/csi-languages`](https://tokconnect.com/docs/api/reference-lists/#get-reference-csi-languages), e.g. en.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_find_topics` tool with `method: search`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_find_topics",
  "arguments": {
    "method": "search",
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/searches?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/searches",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/searches?${params}`, {
  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:

```json
{
  "data": {
    "channel": "search",
    "hasMore": true,
    "next": "eyJvZmZzZXQiOjN9",
    "tab": "SEARCH",
    "topics": [
      {
        "category": "Fashion > Fashion Tutorials",
        "popularity": 77,
        "queryId": "7661799877281595413",
        "queryText": "what to look for in a lip oil",
        "searchVolume": 384507,
        "trend7d": [
          286756,
          201899,
          179210
        ],
        "videoCount": 0
      },
      {
        "category": "Fashion > Fashion Products > Beauty and Skin Care Products > Beauty Products",
        "popularity": 72,
        "queryId": "41561603",
        "queryText": "Best lip oil",
        "searchVolume": 189105,
        "trend7d": [
          185907,
          210094,
          137831
        ],
        "videoCount": 1113
      },
      {
        "category": "Fashion > Fashion Products > Beauty and Skin Care Products > Beauty Products",
        "popularity": 40,
        "queryId": "7411340654124498950",
        "queryText": "lip oils for lips",
        "searchVolume": 3799,
        "trend7d": [
          4099,
          3499,
          2999
        ],
        "videoCount": 1168
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjN9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.channel`string
- `data.hasMore`boolean
- `data.next`string
- `data.tab`string
- `data.topics`array
- `data.topics[].category`string
- `data.topics[].popularity`integer
- `data.topics[].queryId`string
- `data.topics[].queryText`string
- `data.topics[].searchVolume`integer
- `data.topics[].trend7d`array
- `data.topics[].videoCount`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [A ready-made list (channel)](https://tokconnect.com/docs/api/demand/#get-searches-feed)

`GET /v1/searches/feed`

1 credit per call · Paged

#### Parameters

- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

**2 more optional parameters**

- `channel` (string): Which list. suggested, `content_gap` (high demand, few videos), or a category. **One of** `suggested` `content_gap` `lifestyle` `fashion` `food` `sports` `tourism` `gaming` `science`.
- `language` (string): Language code from [`GET /v1/reference/csi-languages`](https://tokconnect.com/docs/api/reference-lists/#get-reference-csi-languages), e.g. en.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_find_topics` tool with `method: feed`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_find_topics",
  "arguments": {
    "method": "feed",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/searches/feed?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/searches/feed?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJvZmZzZXQiOjN9",
    "tab": "ALL",
    "topics": [
      {
        "category": "TikTok's Featured Content > Others TikTok and Video Contents",
        "popularity": 2,
        "queryId": "7637721127158022164",
        "queryText": "views and likes",
        "searchVolume": 99,
        "trend7d": [
          99,
          299,
          99
        ],
        "videoCount": 194769
      },
      {
        "category": "Local Life > Leisure and Entertainment > Other Leisure and Entertainment Venues",
        "popularity": 93,
        "queryId": "7693004027847507989",
        "queryText": "lucki complex con",
        "searchVolume": 34704706,
        "trend7d": [
          0,
          0,
          0
        ],
        "videoCount": 228448
      },
      {
        "category": "TikTok's Featured Content > Stories/Posting Captions",
        "popularity": 72,
        "queryId": "7478520405142011910",
        "queryText": "#relate",
        "searchVolume": 180718,
        "trend7d": [
          3000,
          700,
          54105
        ],
        "videoCount": 166276
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjN9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.tab`string
- `data.topics`array
- `data.topics[].category`string
- `data.topics[].popularity`integer
- `data.topics[].queryId`string
- `data.topics[].queryText`string
- `data.topics[].searchVolume`integer
- `data.topics[].trend7d`array
- `data.topics[].videoCount`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Trending searches, optionally by category](https://tokconnect.com/docs/api/demand/#get-searches-trending)

`GET /v1/searches/trending`

1 credit per call · Paged

#### Parameters

- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `category` (string): Category tab (default all). **One of** `all` `Fashion` `Food` `Sports` `Tourism` `Gaming` `Science`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_find_topics` tool with `method: trending`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_find_topics",
  "arguments": {
    "method": "trending",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/searches/trending?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/searches/trending?${params}`, {
  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:

```json
{
  "data": {
    "channel": "trending",
    "hasMore": true,
    "next": "eyJvZmZzZXQiOjN9",
    "tab": "all",
    "topics": [
      {
        "category": "Sports > Physical Sports > Sports News > Other Sports News",
        "popularity": 93,
        "queryId": "7701568755255476244",
        "queryText": "gabriel penalty miss ballon dor",
        "searchVolume": 33137737,
        "trend7d": [
          0,
          0,
          0
        ],
        "videoCount": 0
      },
      {
        "category": "Entertainment > Celebrity Entertainment > Celebrity Gossips > Celebrity Gossip News",
        "popularity": 92,
        "queryId": "7690715705234161684",
        "queryText": "taylor swift weddings photos",
        "searchVolume": 25630078,
        "trend7d": [
          1692253,
          593303,
          222388
        ],
        "videoCount": 100
      },
      {
        "category": "Sports > Physical Sports > Sports Competitions > Ball Games",
        "popularity": 92,
        "queryId": "7687094461397991444",
        "queryText": "arsenal vs fleetwood",
        "searchVolume": 23658364,
        "trend7d": [
          300,
          300,
          100
        ],
        "videoCount": 0
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjN9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.channel`string
- `data.hasMore`boolean
- `data.next`string
- `data.tab`string
- `data.topics`array
- `data.topics[].category`string
- `data.topics[].popularity`integer
- `data.topics[].queryId`string
- `data.topics[].queryText`string
- `data.topics[].searchVolume`integer
- `data.topics[].trend7d`array
- `data.topics[].videoCount`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## One TikTok search topic

Everything about one search topic (id = queryId from [`GET /v1/searches`](https://tokconnect.com/docs/api/demand/#get-searches)): detail, daily popularity chart, searcher demographics, related searches, TikTok's content guidance and matching videos. Popularity values are TikTok's readings: never add days together or call them monthly searches.

### [searchVolume, trend, category, top countries](https://tokconnect.com/docs/api/demand/#get-searches-id)

`GET /v1/searches/{id}`

1 credit per call

#### Parameters

- `id` (string, path, required): queryId from [`GET /v1/searches`](https://tokconnect.com/docs/api/demand/#get-searches). Not a video id or keyword.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_topic` tool with `method: detail`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_topic",
  "arguments": {
    "method": "detail",
    "id": "7637721127158022164"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/searches/7637721127158022164" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/searches/7637721127158022164", {
  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:

```json
{
  "data": {
    "topCountries": [
      {
        "country_code": "PH",
        "country_name": "Philippines"
      },
      {
        "country_code": "ID",
        "country_name": "Indonesia"
      },
      {
        "country_code": "NG",
        "country_name": "Nigeria"
      }
    ],
    "topic": {
      "category": "TikTok's Featured Content > Others TikTok and Video Contents",
      "popularity": 2,
      "queryId": "7637721127158022164",
      "queryText": "views and likes",
      "searchVolume": 99,
      "trend7d": [
        99,
        299,
        99
      ],
      "videoCount": 194769
    },
    "usesInsightsVideoEndpoint": false
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.topCountries`array
- `data.topCountries[].country_code`string
- `data.topCountries[].country_name`string
- `data.topic`object
- `data.topic.category`string
- `data.topic.popularity`integer
- `data.topic.queryId`string
- `data.topic.queryText`string
- `data.topic.searchVolume`integer
- `data.topic.trend7d`array
- `data.topic.videoCount`integer
- `data.usesInsightsVideoEndpoint`boolean
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Age, gender and location of searchers](https://tokconnect.com/docs/api/demand/#get-searches-id-audience)

`GET /v1/searches/{id}/audience`

1 credit per call

#### Parameters

- `id` (string, path, required): queryId from [`GET /v1/searches`](https://tokconnect.com/docs/api/demand/#get-searches). Not a video id or keyword.

**1 more optional parameter**

- `days` (string): Window in days (default 30). **One of** `7` `30` `60` `180`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_topic` tool with `method: audience`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_topic",
  "arguments": {
    "method": "audience",
    "id": "7637721127158022164"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/searches/7637721127158022164/audience" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/searches/7637721127158022164/audience", {
  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:

```json
{
  "data": {
    "age": [
      {
        "category": "total",
        "popularity": 96667
      },
      {
        "category": "25-34",
        "popularity": 32190
      },
      {
        "category": "18-24",
        "popularity": 26891
      }
    ],
    "gender": [
      {
        "category": "total",
        "popularity": 96669
      },
      {
        "category": "unknown",
        "popularity": 50284
      },
      {
        "category": "male",
        "popularity": 24492
      }
    ],
    "location": [
      {
        "category": "total",
        "popularity": 96586
      },
      {
        "category": "Indonesia",
        "popularity": 12896
      },
      {
        "category": "Pakistan",
        "popularity": 10696
      }
    ],
    "summary": {
      "age": "25-34",
      "gender": "unknown",
      "location": "Indonesia"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.age`array
- `data.age[].category`string
- `data.age[].popularity`integer
- `data.gender`array
- `data.gender[].category`string
- `data.gender[].popularity`integer
- `data.location`array
- `data.location[].category`string
- `data.location[].popularity`integer
- `data.summary`object
- `data.summary.age`string
- `data.summary.gender`string
- `data.summary.location`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [TikTok's suggested hooks, hashtags and outlines (often unavailable)](https://tokconnect.com/docs/api/demand/#get-searches-id-guidance)

`GET /v1/searches/{id}/guidance`

1 credit per call

#### Parameters

- `id` (string, path, required): queryId from [`GET /v1/searches`](https://tokconnect.com/docs/api/demand/#get-searches). Not a video id or keyword.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_topic` tool with `method: guidance`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_topic",
  "arguments": {
    "method": "guidance",
    "id": "7637721127158022164"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/searches/7637721127158022164/guidance" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/searches/7637721127158022164/guidance", {
  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:

```json
{
  "data": {
    "available": false,
    "message": "TikTok reports that content guidance is not generated for this CSI topic yet. No guidance is available in this response."
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.available`boolean
- `data.message`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Daily popularity chart, worldwide or per country](https://tokconnect.com/docs/api/demand/#get-searches-id-popularity)

`GET /v1/searches/{id}/popularity`

1 credit per call

#### Parameters

- `id` (string, path, required): queryId from [`GET /v1/searches`](https://tokconnect.com/docs/api/demand/#get-searches). Not a video id or keyword.

**2 more optional parameters**

- `countries` (array of string): Country codes to break out, e.g. "US","GB". Omit for worldwide.
- `days` (string): Window in days (default 30). **One of** `7` `30` `60` `180`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_topic` tool with `method: popularity`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_topic",
  "arguments": {
    "method": "popularity",
    "id": "7637721127158022164"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/searches/7637721127158022164/popularity" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/searches/7637721127158022164/popularity", {
  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:

```json
{
  "data": {
    "series": [
      {
        "country": "global",
        "points": [
          {
            "date": "2026-09-30",
            "popularity": 1481
          },
          {
            "date": "2026-10-01",
            "popularity": 1093
          },
          {
            "date": "2026-10-02",
            "popularity": 701
          }
        ]
      }
    ],
    "windowDays": 30
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.series`array
- `data.series[].country`string
- `data.series[].points`array
- `data.series[].points[].date`string
- `data.series[].points[].popularity`integer
- `data.windowDays`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Related searches with their searchVolume](https://tokconnect.com/docs/api/demand/#get-searches-id-related)

`GET /v1/searches/{id}/related`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): queryId from [`GET /v1/searches`](https://tokconnect.com/docs/api/demand/#get-searches). Not a video id or keyword.
- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_topic` tool with `method: related`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_topic",
  "arguments": {
    "method": "related",
    "id": "7637721127158022164",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/searches/7637721127158022164/related?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/searches/7637721127158022164/related?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJvZmZzZXQiOjN9",
    "topics": [
      {
        "category": "Fashion > Fashion Tutorials > Beauty and Skin Care Tutorials > Beauty Tutorials",
        "popularity": 4,
        "queryId": "7482230116668489734",
        "queryText": "Make. Up",
        "searchVolume": 199,
        "trend7d": [
          0,
          199,
          99
        ],
        "videoCount": 8549
      },
      {
        "category": "Science and Technology > Internet > Internet Entrepreneurship Knowledge > Self-Media Operation Knowledge",
        "popularity": 72,
        "queryId": "7417365957699534853",
        "queryText": "More likes",
        "searchVolume": 181454,
        "trend7d": [
          124737,
          176552,
          44413
        ],
        "videoCount": 408803
      },
      {
        "category": "Science and Technology > Internet > Internet Entrepreneurship Knowledge > Self-Media Operation Knowledge",
        "popularity": 65,
        "queryId": "7411340955263123461",
        "queryText": "more views",
        "searchVolume": 50974,
        "trend7d": [
          121239,
          2898,
          12693
        ],
        "videoCount": 29439
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjN9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.topics`array
- `data.topics[].category`string
- `data.topics[].popularity`integer
- `data.topics[].queryId`string
- `data.topics[].queryText`string
- `data.topics[].searchVolume`integer
- `data.topics[].trend7d`array
- `data.topics[].videoCount`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Videos TikTok shows for the topic](https://tokconnect.com/docs/api/demand/#get-searches-id-videos)

`GET /v1/searches/{id}/videos`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): queryId from [`GET /v1/searches`](https://tokconnect.com/docs/api/demand/#get-searches). Not a video id or keyword.
- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_topic` tool with `method: videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_topic",
  "arguments": {
    "method": "videos",
    "id": "7637721127158022164",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/searches/7637721127158022164/videos?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/searches/7637721127158022164/videos?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJvZmZzZXQiOjN9",
    "topicQueryId": "7637721127158022164",
    "topicQueryText": "views and likes",
    "videos": [
      {
        "caption": "going viral does NOT have to be super complicated!! #iwanttogoviral #howtogoviralontiktok #howtogoviraltips #tiktokgrowth",
        "comments": 55778,
        "creator": {
          "followers": 18459,
          "handle": "thelifeofjftb",
          "id": "6895909988976395270",
          "nickname": "jenny",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 89.634,
        "hashtags": [
          {
            "id": "85581100",
            "name": "iwanttogoviral"
          },
          {
            "id": "1645041228246018",
            "name": "howtogoviralontiktok"
          }
        ],
        "id": "7516402158825196846",
        "language": "en",
        "likes": 200636,
        "posted": "2025-06-16T04:39:53Z",
        "saves": 78023,
        "shares": 75002,
        "sound": {
          "author": "jenny",
          "id": "7516402224461892395",
          "original": true,
          "title": "original sound - thelifeofjftb"
        },
        "url": "https://www.tiktok.com/@thelifeofjftb/video/7516402158825196846",
        "views": 2086466
      },
      {
        "caption": "The views may be low but unfortunately I’ve already decided I’m famous 😭😂 #TikTokHumor #SmallCreator #MainCharacterEnergy #ForYou #KeepPosting",
        "comments": 8422,
        "creator": {
          "followers": 2868,
          "handle": "thehouseofsamuel",
          "id": "7605020458355196941",
          "nickname": "The House Of Samuel",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 6.547,
        "hashtags": [
          {
            "id": "1589764631152642",
            "name": "tiktokhumor"
          },
          {
            "id": "1609436969656325",
            "name": "smallcreator"
          }
        ],
        "id": "7693916067256749343",
        "language": "en",
        "likes": 157523,
        "posted": "2026-10-07T13:24:33Z",
        "saves": 22839,
        "shares": 8585,
        "sound": {
          "author": "AngieBLoveee🇺🇸",
          "id": "7414631646038625066",
          "original": true,
          "title": "Imma keep posting"
        },
        "url": "https://www.tiktok.com/@thehouseofsamuel/video/7693916067256749343",
        "views": 1088039
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjN9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.topicQueryId`string
- `data.topicQueryText`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.followers`integer
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].durationSec`number
- `data.videos[].hashtags`array
- `data.videos[].hashtags[].id`string
- `data.videos[].hashtags[].name`string
- `data.videos[].id`string
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.original`boolean
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Follow-up searches TikTok links to it](https://tokconnect.com/docs/api/demand/#get-searches-id-related-queries)

`GET /v1/searches/{id}/related-queries`

1 credit per call

#### Parameters

- `id` (string, path, required): queryId from [`GET /v1/searches`](https://tokconnect.com/docs/api/demand/#get-searches). Not a video id or keyword.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_topic` tool with `method: related_queries`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_topic",
  "arguments": {
    "method": "related_queries",
    "id": "7637721127158022164"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/searches/7637721127158022164/related-queries" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/searches/7637721127158022164/related-queries", {
  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 (this capture matched nothing):

```json
{
  "data": {
    "queries": []
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.queries`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Keyword suggestions

Autocomplete and keyword ideas from TikTok and TikTok Shop. [`GET /v1/keywords/signals`](https://tokconnect.com/docs/api/demand/#get-keywords-signals) adds TikTok's predicted click-through and a shopping-intent flag per phrase. These rank phrases; they are not search volume (use [`GET /v1/searches`](https://tokconnect.com/docs/api/demand/#get-searches) for volume).

### [Account (@handle) suggestions](https://tokconnect.com/docs/api/demand/#get-keywords-accounts)

`GET /v1/keywords/accounts`

1 credit per call

#### Parameters

- `keyword` (string): Seed phrase, for example lip oil.
- `limit` (integer): Results per page. Max 50. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_keywords` tool with `method: accounts`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_keywords",
  "arguments": {
    "method": "accounts",
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/keywords/accounts?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/keywords/accounts",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/keywords/accounts?${params}`, {
  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:

```json
{
  "data": {
    "suggestions": [
      "lip oil",
      "Lip Oil",
      "Lip oil"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.suggestions`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [TikTok Shop search autocomplete](https://tokconnect.com/docs/api/demand/#get-keywords-shop)

`GET /v1/keywords/shop`

1 credit per call

#### Parameters

- `keyword` (string): Seed phrase, for example lip oil.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_keywords` tool with `method: shop`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_keywords",
  "arguments": {
    "method": "shop",
    "keyword": "lip oil"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/keywords/shop?keyword=lip%20oil" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
});
const res = await fetch(`https://api.tokconnect.com/v1/keywords/shop?${params}`, {
  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:

```json
{
  "data": {
    "page": "suggest",
    "suggestions": [
      "lip oil hydration",
      "lip oil stain",
      "lip oil gloss"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.page`string
- `data.suggestions`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Autocomplete with click-through and shopping-intent signals](https://tokconnect.com/docs/api/demand/#get-keywords-signals)

`GET /v1/keywords/signals`

1 credit per call

#### Parameters

- `keyword` (string): Seed phrase, for example lip oil.
- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_keywords` tool with `method: signals`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_keywords",
  "arguments": {
    "method": "signals",
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/keywords/signals?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/keywords/signals",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/keywords/signals?${params}`, {
  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:

```json
{
  "data": {
    "keyword": "lip oil",
    "suggestions": [
      {
        "ecomIntent": 2,
        "predictedCtr": 0.026337544,
        "text": "lip oil"
      },
      {
        "ecomIntent": 1,
        "predictedCtr": 0.0067250463,
        "text": "lip oil vs lip gloss"
      },
      {
        "ecomIntent": 2,
        "predictedCtr": 0.0041258996,
        "text": "Lip oil essence"
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.keyword`string
- `data.suggestions`array
- `data.suggestions[].ecomIntent`integer
- `data.suggestions[].predictedCtr`number
- `data.suggestions[].text`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [TikTok search autocomplete](https://tokconnect.com/docs/api/demand/#get-keywords-suggest)

`GET /v1/keywords/suggest`

1 credit per call

#### Parameters

- `keyword` (string): Seed phrase, for example lip oil.
- `limit` (integer): Results per page. Max 50. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_keywords` tool with `method: tiktok`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_keywords",
  "arguments": {
    "method": "tiktok",
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/keywords/suggest?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/keywords/suggest",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/keywords/suggest?${params}`, {
  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:

```json
{
  "data": {
    "suggestions": [
      "lip oil",
      "lip oil vs lip gloss",
      "Lip oil essence"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.suggestions`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Trending phrases TikTok's website shows](https://tokconnect.com/docs/api/demand/#get-keywords-trending)

`GET /v1/keywords/trending`

1 credit per call

#### Parameters

- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_keywords` tool with `method: trending`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_keywords",
  "arguments": {
    "method": "trending",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/keywords/trending?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/keywords/trending?${params}`, {
  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:

```json
{
  "data": {
    "searches": [
      "Hyena makeup for Halloween trend",
      "Band Aid and 2 Pimple Patches remarks trend",
      "Fancy Footwork trend"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.searches`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [EU/UK Ad Library advertiser and keyword autocomplete](https://tokconnect.com/docs/api/demand/#get-keywords-ad-library)

`GET /v1/keywords/ad-library`

1 credit per call · EU and UK

#### Parameters

- `keyword` (string): Seed phrase, for example lip oil.
- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

**2 more optional parameters**

- `region` (string): 2-letter EU or UK country from [`GET /v1/reference/ad-regions`](https://tokconnect.com/docs/api/reference-lists/#get-reference-ad-regions). Default DE.
- `suggest_type` (string): TikTok's suggestion type, default 1 (advertisers and keywords).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `demand_keywords` tool with `method: ad_library`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "demand_keywords",
  "arguments": {
    "method": "ad_library",
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/keywords/ad-library?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/keywords/ad-library",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/keywords/ad-library?${params}`, {
  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 (this capture matched nothing):

```json
{
  "data": {
    "advertisers": [],
    "code": 0,
    "keywords": []
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.advertisers`array
- `data.code`integer
- `data.keywords`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/demand/

---

# TikTok Shop categories API

TikTok Shop categories ranked by revenue and growth, the category tree with ids, and a category's top products. To rank products inside a category, use [Rankings](https://tokconnect.com/docs/api/rankings/).

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

Call these routes with your own key, or ask the same question in plain words.

[Get an API key](https://app.tokconnect.com/api-key)[Ask about a category](https://app.tokconnect.com/?q=Which%20TikTok%20Shop%20categories%20grew%20fastest%20in%20the%20US%20this%20month%3F)[Try it free in Shop Analytics](https://tokconnect.com/tools/tiktok-shop-analytics/)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/categories/market-size`](https://tokconnect.com/docs/api/categories/#get-categories-market-size) | How many products, shops, creators, videos, LIVEs and brands TokConnect tracks |
| [GET `/v1/categories/products`](https://tokconnect.com/docs/api/categories/#get-categories-products) | A category's top product ids (US market only) |
| [GET `/v1/categories/search`](https://tokconnect.com/docs/api/categories/#get-categories-search) | Find category names and ids by keyword |
| [GET `/v1/categories/top`](https://tokconnect.com/docs/api/categories/#get-categories-top) | Categories with revenue, growth and concentration |
| [GET `/v1/categories/tree`](https://tokconnect.com/docs/api/categories/#get-categories-tree) | Category names and ids to use as category |

## Common parameters

These read the same on the routes below that take them.

- `region` (string): Market as an ISO country code, default US. Amounts are in the market's currency. See [Markets](https://tokconnect.com/docs/api/markets/).
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## TikTok Shop category trends

Shop Analytics

The top TikTok Shop categories by estimated revenue over the last 7 days of data: revenue, units, growth, revenue per shop, top-3 and top-10 shop share, split by video, LIVE and affiliate.

[`GET /v1/categories/tree`](https://tokconnect.com/docs/api/categories/#get-categories-tree) lists category names and ids (pass them as category to the product and creator rankings). [`GET /v1/categories/products`](https://tokconnect.com/docs/api/categories/#get-categories-products) returns a category's top product ids. [`GET /v1/categories/market-size`](https://tokconnect.com/docs/api/categories/#get-categories-market-size) counts what TokConnect Shop Analytics tracks in a market, not all of TikTok Shop.

### [How many products, shops, creators, videos, LIVEs and brands TokConnect tracks](https://tokconnect.com/docs/api/categories/#get-categories-market-size)

`GET /v1/categories/market-size`

1 credit per call · Shop Analytics · 17 markets

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/categories/#common-parameters).

The start, end and window parameters are accepted but not used here: the totals are as of the last day of data.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `category_trends` tool with `method: market_size`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "category_trends",
  "arguments": {
    "method": "market_size"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/categories/market-size" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/categories/market-size", {
  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:

```json
{
  "data": {
    "counts": {
      "brands": 21214,
      "creators": 277023,
      "livestreams": 191201,
      "products": 1041879,
      "shops": 114343,
      "videos": 1441803
    },
    "dataEnd": "2026-10-28",
    "market": "US",
    "notes": [
      "Market US (United States)."
    ],
    "scope": "Totals tracked by TokConnect in this market, not all of TikTok Shop. They size what Shop Analytics tracks, not sales, and not every seller, creator or video on TikTok.",
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price."
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.counts`object
- `data.counts.brands`integer
- `data.counts.creators`integer
- `data.counts.livestreams`integer
- `data.counts.products`integer
- `data.counts.shops`integer
- `data.counts.videos`integer
- `data.dataEnd`string
- `data.market`string
- `data.notes`array
- `data.scope`string
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [A category's top product ids (US market only)](https://tokconnect.com/docs/api/categories/#get-categories-products)

`GET /v1/categories/products`

1 credit per call · Shop Analytics · US only

#### Parameters

- `category` (string): Category name exactly as [`GET /v1/categories/top`](https://tokconnect.com/docs/api/categories/#get-categories-top) returns it (the `cate_id` field), for example 'Beauty & Personal Care'.

**4 more optional parameters**

- `end` (string): Custom range end, YYYY-MM-DD (capped at the last complete day).
- `region` (string): US only: other markets are refused.
- `start` (string): Custom range start, YYYY-MM-DD.
- `window` (string): Date range ending at the last complete day (about 2 days ago). Default 30d. Use start and end for a custom range. **One of** `7d` `30d` `90d` `180d` `365d`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `category_trends` tool with `method: products`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "category_trends",
  "arguments": {
    "method": "products",
    "category": "Beauty & Personal Care"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/categories/products?category=Beauty%20%26%20Personal%20Care" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/categories/products",
    params={
        "category": "Beauty & Personal Care",
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  category: "Beauty & Personal Care",
});
const res = await fetch(`https://api.tokconnect.com/v1/categories/products?${params}`, {
  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:

```json
{
  "data": {
    "category": "Beauty & Personal Care",
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "groups": [
      {
        "cate_id": "Beauty & Personal Care",
        "product": [
          {
            "id": "1732738686074327162"
          },
          {
            "id": "1732738538912714757"
          },
          {
            "id": "1732052189676081387"
          }
        ]
      }
    ],
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "see_also": "Pass these ids to product method=sales with ids=[...] for revenue and units, or product_top_selling with a keyword for a full ranking.",
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 30,
      "end": "2026-10-28",
      "start": "2026-09-29"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.category`string
- `data.currency`string
- `data.dataEnd`string
- `data.groups`array
- `data.groups[].cate_id`string
- `data.groups[].product`array
- `data.groups[].product[].id`string
- `data.market`string
- `data.notes`array
- `data.see_also`string
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Find category names and ids by keyword](https://tokconnect.com/docs/api/categories/#get-categories-search)

`GET /v1/categories/search`

1 credit per call · Shop Analytics · 17 markets

#### Parameters

- `keyword` (string): Text to find in category names, for example 'skincare'.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `category_trends` tool with `method: search`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "category_trends",
  "arguments": {
    "method": "search",
    "keyword": "lip oil"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/categories/search?keyword=lip%20oil" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
});
const res = await fetch(`https://api.tokconnect.com/v1/categories/search?${params}`, {
  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:

```json
{
  "data": {
    "currency": "USD",
    "items": [
      {
        "id": 805640,
        "name": "Kids' Fashion-Boys' Footwear-Slippers",
        "score": 0
      },
      {
        "id": 806536,
        "name": "Kids' Fashion-Girls' Footwear-Slippers",
        "score": 0
      },
      {
        "id": 601374,
        "name": "Shoes-Men's Shoes-Slippers",
        "score": 0
      }
    ],
    "keyword": "lip oil",
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD."
    ],
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price."
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.currency`string
- `data.items`array
- `data.items[].id`integer
- `data.items[].name`string
- `data.items[].score`integer
- `data.keyword`string
- `data.market`string
- `data.notes`array
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Categories with revenue, growth and concentration](https://tokconnect.com/docs/api/categories/#get-categories-top)

`GET /v1/categories/top`

1 credit per call · Shop Analytics · 17 markets

#### Parameters

- `level` (string): Keep only categories of this level (1 = top level, 3 = most specific). **One of** `1` `2` `3`.

The start, end and window parameters are accepted but not used here: category figures cover the last 7 days of data.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `category_trends` tool with `method: list`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "category_trends",
  "arguments": {
    "method": "list"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/categories/top" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/categories/top", {
  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:

```json
{
  "data": {
    "count": 10,
    "currency": "USD",
    "dataEnd": "2026-10-28",
    "items": [
      {
        "affiliate_revenue": "$72.32m",
        "average_revenue": "$5.67k",
        "cate_id": "Beauty & Personal Care",
        "date_interval": "7d",
        "id": "601450",
        "level": "1",
        "live_revenue": "$16.40m",
        "name": "Beauty & Personal Care",
        "revenue": "$89.73m",
        "revenue_growth_rate": -0.1423943532521982,
        "revenue_trend": [
          1222082970,
          1304434512,
          1093114419
        ],
        "self_promotion_revenue": "$7.23m",
        "shop_number": 15829,
        "shopping_mall_revenue": "$10.19m",
        "showcase_revenue": "$12.93m",
        "top_10_shop_revenue_ratio": 0.184013778054234,
        "top_3_shop_revenue_ratio": 0.09835574995436176,
        "video_revenue": "$60.40m"
      },
      {
        "affiliate_revenue": "$59.36m",
        "average_revenue": "$5.39k",
        "cate_id": "Womenswear & Underwear",
        "date_interval": "7d",
        "id": "601152",
        "level": "1",
        "live_revenue": "$9.50m",
        "name": "Womenswear & Underwear",
        "revenue": "$73.80m",
        "revenue_growth_rate": -0.21692984191843792,
        "revenue_trend": [
          946945250,
          1094214841.5,
          827028189
        ],
        "self_promotion_revenue": "$7.17m",
        "shop_number": 13701,
        "shopping_mall_revenue": "$7.26m",
        "showcase_revenue": "$10.49m",
        "top_10_shop_revenue_ratio": 0.15677009265967165,
        "top_3_shop_revenue_ratio": 0.07922574659084249,
        "video_revenue": "$53.81m"
      },
      {
        "affiliate_revenue": "$25.90m",
        "average_revenue": "$2.66k",
        "cate_id": "Sports & Outdoor",
        "date_interval": "7d",
        "id": "603014",
        "level": "1",
        "live_revenue": "$4.88m",
        "name": "Sports & Outdoor",
        "revenue": "$34.18m",
        "revenue_growth_rate": -0.10448608774096589,
        "revenue_trend": [
          483660312,
          505927939,
          419452406
        ],
        "self_promotion_revenue": "$3.31m",
        "shop_number": 12859,
        "shopping_mall_revenue": "$4.97m",
        "showcase_revenue": "$6.87m",
        "top_10_shop_revenue_ratio": 0.20453100930944212,
        "top_3_shop_revenue_ratio": 0.11515856825031943,
        "video_revenue": "$22.43m"
      }
    ],
    "market": "US",
    "notes": [
      "Market US (United States): amounts are in USD.",
      "Category figures always cover the last 7 days of data (window below), whatever window you ask for. For a longer view of one category, rank its products with product_top_selling and a keyword."
    ],
    "see_also": "Pass a row's cate_id as category to category_trends method=products for its top product ids.",
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price.",
    "window": {
      "days": 7,
      "end": "2026-10-28",
      "start": "2026-10-22"
    }
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.currency`string
- `data.dataEnd`string
- `data.items`array
- `data.items[].affiliate_revenue`string
- `data.items[].average_revenue`string
- `data.items[].cate_id`string
- `data.items[].date_interval`string
- `data.items[].id`string
- `data.items[].level`string
- `data.items[].live_revenue`string
- `data.items[].name`string
- `data.items[].revenue`string
- `data.items[].revenue_growth_rate`number
- `data.items[].revenue_trend`array
- `data.items[].self_promotion_revenue`string
- `data.items[].shop_number`integer
- `data.items[].shopping_mall_revenue`string
- `data.items[].showcase_revenue`string
- `data.items[].top_10_shop_revenue_ratio`number
- `data.items[].top_3_shop_revenue_ratio`number
- `data.items[].video_revenue`string
- `data.market`string
- `data.notes`array
- `data.see_also`string
- `data.source`string
- `data.window`object
- `data.window.days`integer
- `data.window.end`string
- `data.window.start`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Category names and ids to use as category](https://tokconnect.com/docs/api/categories/#get-categories-tree)

`GET /v1/categories/tree`

1 credit per call · Shop Analytics

#### Parameters

- `limit` (integer): Max categories to return (default 50).

**2 more optional parameters**

- `keyword` (string): Text to find in category names, for example 'skincare'.
- `level` (string): Keep only categories of this level (1 = top level, 3 = most specific). **One of** `1` `2` `3`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `category_trends` tool with `method: tree`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "category_trends",
  "arguments": {
    "method": "tree",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/categories/tree?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/categories/tree?${params}`, {
  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:

```json
{
  "data": {
    "count": 3,
    "hasMore": true,
    "items": [
      {
        "id": "600001",
        "level": 1,
        "name": "Home Supplies"
      },
      {
        "id": "600024",
        "level": 1,
        "name": "Kitchenware"
      },
      {
        "id": "600154",
        "level": 1,
        "name": "Textiles & Soft Furnishings"
      }
    ],
    "matched": 26,
    "see_also": "Pass an id or name as category to product_top_selling or creator_top_selling. Names are the US English category names; ids are the source's own.",
    "source": "TokConnect Shop Analytics (TikTok Shop US). Revenue and units are estimates: units track TikTok's sold counter; revenue is units times listed price."
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.hasMore`boolean
- `data.items`array
- `data.items[].id`string
- `data.items[].level`integer
- `data.items[].name`string
- `data.matched`integer
- `data.see_also`string
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/categories/

---

# TikTok ads library and Creative Center API

TikTok's ads library and Creative Center: search ads by keyword, see where each ad ran and, when TikTok provides it, how viewers held on second by second, plus trending videos by market, SEO inspiration lists and Creative Partner agencies.

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

Call these routes with your own key, or ask the same question in plain words.

[Get an API key](https://app.tokconnect.com/api-key)[Ask the same in plain words](https://app.tokconnect.com/?q=Top%20TikTok%20ads%20for%20lip%20oil)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/ads/search`](https://tokconnect.com/docs/api/creative-center/#get-ads-search) | Top ads matching keyword (worldwide) |
| [GET `/v1/ads/{id}`](https://tokconnect.com/docs/api/creative-center/#get-ads-id) | One ad: countries, CTR, likes, objective, landing page, video |
| [GET `/v1/ads/{id}/analysis`](https://tokconnect.com/docs/api/creative-center/#get-ads-id-analysis) | Retention curve per second, biggest drop, CTR percentile |
| [GET `/v1/ads/{id}/similar`](https://tokconnect.com/docs/api/creative-center/#get-ads-id-similar) | Ads TikTok recommends next to this one |
| [GET `/v1/creative-center/seo/detail`](https://tokconnect.com/docs/api/creative-center/#get-creative-center-seo-detail) | Detail for names from seo_list |
| [GET `/v1/creative-center/top-videos`](https://tokconnect.com/docs/api/creative-center/#get-creative-center-top-videos) | Trending videos by market with engagement |
| [GET `/v1/creative-center/partners`](https://tokconnect.com/docs/api/creative-center/#get-creative-center-partners) | Creative Partner agencies for a market |
| [GET `/v1/creative-center/seo`](https://tokconnect.com/docs/api/creative-center/#get-creative-center-seo) | Public SEO inspiration names by type |

## Common parameters

These read the same on the routes below that take them.

- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## TikTok top ads library

TikTok's library of top-performing ads: search by keyword, then open one ad for the countries it ran in, CTR, likes, objective, landing page and video. The analysis route returns TikTok's per-second retention curve when TikTok provides one, and the ad's CTR percentile against other ads. Ad copy in the examples is in the ad's own language.

Search results are worldwide: the library does not filter by market. Read each ad's countries from [`GET /v1/ads/{id}`](https://tokconnect.com/docs/api/creative-center/#get-ads-id). Checked 31 October 2026: searches for US, DE and JP, and with a language filter, returned the same ads.

### [Top ads matching keyword (worldwide)](https://tokconnect.com/docs/api/creative-center/#get-ads-search)

`GET /v1/ads/search`

1 credit per call · Paged

#### Parameters

- `keyword` (string): Phrase in the ad, e.g. 'skincare'. Omit to list top ads of the period.
- `limit` (integer): Results per page. Max 50. Values above the maximum are lowered and reported in notes.

**2 more optional parameters**

- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `period` (string): Ads from the last 7, 30 or 180 days (default 30). **One of** `7` `30` `180`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `ad_library` tool with `method: search`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "ad_library",
  "arguments": {
    "method": "search",
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/ads/search?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/ads/search",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/ads/search?${params}`, {
  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:

```json
{
  "data": {
    "as_of": "2026-10-30T23:27:06Z",
    "count": 3,
    "has_more": true,
    "items": [
      {
        "brand": "",
        "cover": "(signed media URL)",
        "ctr": 0.96,
        "duration": 47.534,
        "id": "7689369336687034388",
        "industry": "14104000000",
        "likes": 167,
        "objective": "reach",
        "title": "Kalau korang area SG Besi, jangan scroll dulu 👀🔥 Ada satu spot yang korang kena try sendiri! ✨ Zufora SG Besi — sesuai untuk korang yang suka cantikkan diri dari segi makeup , supplement dan macam2 lagi 🌸 Jangan lupa waze  📍Zufora, SG Besi…"
      },
      {
        "brand": "medicube",
        "cover": "(signed media URL)",
        "ctr": 0.78,
        "duration": 80.214,
        "id": "7693690323848609793",
        "industry": "14109000000",
        "likes": 7,
        "objective": "conversion",
        "title": "50% OFF PLUS FREE SHIPPING "
      },
      {
        "brand": "",
        "cover": "(signed media URL)",
        "ctr": 0.62,
        "duration": 108.252,
        "id": "7391864211066601473",
        "industry": "23122000000",
        "likes": 0,
        "objective": "product_sales",
        "title": "Are you ready to build a skincare routine that actually works? You've come to the right video! Watch the first episode of our Skincare 101 series ▶️🩷 #kbeautycafe #skincareroutine #skincareforbeginners #skincare #koreanskincare…"
      }
    ],
    "market": "worldwide",
    "next": "eyJwYWdlIjoyfQ",
    "notes": [
      "ctr and likes are TikTok's ad library figures for the ad; objective and industry are TikTok's labels.",
      "The ad library answers worldwide; method=detail lists the countries each ad ran in."
    ],
    "period_days": 30,
    "see_also": [
      "ad_library method=detail id=<items[].id>",
      "ad_library method=analysis id=<items[].id>"
    ],
    "total": 33
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyfQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.count`integer
- `data.has_more`boolean
- `data.items`array
- `data.items[].brand`string
- `data.items[].cover`string
- `data.items[].ctr`number
- `data.items[].duration`number
- `data.items[].id`string
- `data.items[].industry`string
- `data.items[].likes`integer
- `data.items[].objective`string
- `data.items[].title`string
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.period_days`integer
- `data.see_also`array
- `data.source`string
- `data.total`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [One ad: countries, CTR, likes, objective, landing page, video](https://tokconnect.com/docs/api/creative-center/#get-ads-id)

`GET /v1/ads/{id}`

1 credit per call

#### Parameters

- `id` (string, path, required): Ad id (`items[].id` from [`GET /v1/ads/search`](https://tokconnect.com/docs/api/creative-center/#get-ads-search) or similar).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `ad_library` tool with `method: detail`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "ad_library",
  "arguments": {
    "method": "detail",
    "id": "7689369336687034388"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/ads/7689369336687034388" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/ads/7689369336687034388", {
  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:

```json
{
  "data": {
    "ad": {
      "brand": "",
      "comments": 2,
      "countries": [
        "MY"
      ],
      "cover": "(signed media URL)",
      "ctr": 0.96,
      "duration": 47.534,
      "id": "7689369336687034388",
      "industry": "14104000000",
      "likes": 167,
      "objective": "reach",
      "shares": 4,
      "source": "Others",
      "title": "Kalau korang area SG Besi, jangan scroll dulu 👀🔥 Ada satu spot yang korang kena try sendiri! ✨ Zufora SG Besi — sesuai untuk korang yang suka cantikkan diri dari segi makeup , supplement dan macam2 lagi 🌸 Jangan lupa waze  📍Zufora, SG Besi…",
      "video_url": "(signed media URL)",
      "voice_over": false
    },
    "as_of": "2026-10-30T23:27:07Z",
    "notes": [
      "ctr and likes are TikTok's ad library figures for the ad; objective and industry are TikTok's labels."
    ],
    "see_also": [
      "ad_library method=analysis id=7689369336687034388",
      "ad_library method=similar id=7689369336687034388"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.ad`object
- `data.ad.brand`string
- `data.ad.comments`integer
- `data.ad.countries`array
- `data.ad.cover`string
- `data.ad.ctr`number
- `data.ad.duration`number
- `data.ad.id`string
- `data.ad.industry`string
- `data.ad.likes`integer
- `data.ad.objective`string
- `data.ad.shares`integer
- `data.ad.source`string
- `data.ad.title`string
- `data.ad.video_url`string
- `data.ad.voice_over`boolean
- `data.as_of`string
- `data.notes`array
- `data.see_also`array
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Retention curve per second, biggest drop, CTR percentile](https://tokconnect.com/docs/api/creative-center/#get-ads-id-analysis)

`GET /v1/ads/{id}/analysis`

1 credit per call

#### Parameters

- `id` (string, path, required): Ad id (`items[].id` from [`GET /v1/ads/search`](https://tokconnect.com/docs/api/creative-center/#get-ads-search) or similar).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `ad_library` tool with `method: analysis`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "ad_library",
  "arguments": {
    "method": "analysis",
    "id": "7689369336687034388"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/ads/7689369336687034388/analysis" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/ads/7689369336687034388/analysis", {
  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:

```json
{
  "data": {
    "as_of": "2026-10-30T23:27:09Z",
    "ctr_percentile": 0.99,
    "duration": 49,
    "id": "7689369336687034388",
    "notes": [
      "Calls made: TikTok's keyframe retention analysis and its CTR percentile for the ad.",
      "TikTok returned no retention data for this ad (every point was 0), so no curve is shown.",
      "ctr_percentile is TikTok's rank of the ad's click-through rate among ads over 180 days (0.99 = top 1%)."
    ],
    "see_also": [
      "ad_library method=detail id=7689369336687034388"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.ctr_percentile`number
- `data.duration`integer
- `data.id`string
- `data.notes`array
- `data.see_also`array
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Ads TikTok recommends next to this one](https://tokconnect.com/docs/api/creative-center/#get-ads-id-similar)

`GET /v1/ads/{id}/similar`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Ad id (`items[].id` from [`GET /v1/ads/search`](https://tokconnect.com/docs/api/creative-center/#get-ads-search) or similar).
- `limit` (integer): Results per page. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `ad_library` tool with `method: similar`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "ad_library",
  "arguments": {
    "method": "similar",
    "id": "7689369336687034388",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/ads/7689369336687034388/similar?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/ads/7689369336687034388/similar?${params}`, {
  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:

```json
{
  "data": {
    "as_of": "2026-10-30T23:27:12Z",
    "count": 1,
    "has_more": false,
    "id": "7689369336687034388",
    "items": [
      {
        "brand": "",
        "cover": "(signed media URL)",
        "ctr": 0.83,
        "duration": 28.84,
        "id": "7692455584689340423",
        "industry": "14104000000",
        "likes": 785,
        "objective": "product_sales",
        "title": "銀座に旗艦店がある、フローリアス(花西子)のUVクッションファンデ。本場中国のドール肌、宮廷時代から磨かれ続けた微細粒子と先端技術のUVカット。試してみない？ #とくとくセール #ショップ始めました #ファンデーショ…"
      }
    ],
    "notes": [
      "ctr and likes are TikTok's ad library figures for the ad; objective and industry are TikTok's labels.",
      "Calls made: the ad's detail (industry 14104000000, country MY), then TikTok's recommended ads for them."
    ],
    "see_also": [
      "ad_library method=detail id=<items[].id>"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.count`integer
- `data.has_more`boolean
- `data.id`string
- `data.items`array
- `data.items[].brand`string
- `data.items[].cover`string
- `data.items[].ctr`number
- `data.items[].duration`number
- `data.items[].id`string
- `data.items[].industry`string
- `data.items[].likes`integer
- `data.items[].objective`string
- `data.items[].title`string
- `data.notes`array
- `data.see_also`array
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## TikTok Creative Center

TikTok Creative Center: top videos by market (US, JP, VN, TH, ID), public SEO inspiration lists, and Creative Partner agency leaderboards. Partners take a market code from [`GET /v1/reference/creative-markets`](https://tokconnect.com/docs/api/reference-lists/#get-reference-creative-markets).

### [Detail for names from seo_list](https://tokconnect.com/docs/api/creative-center/#get-creative-center-seo-detail)

`GET /v1/creative-center/seo/detail`

1 credit per call

#### Parameters

- `biz_type` (string): Which list. **One of** `keyword` `hashtag` `selling_points` `top_content` `top_ads`.
- `names` (array of string): Exact names from [`GET /v1/creative-center/seo`](https://tokconnect.com/docs/api/creative-center/#get-creative-center-seo).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creative_center` tool with `method: seo_detail`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creative_center",
  "arguments": {
    "method": "seo_detail",
    "biz_type": "hashtag",
    "names": [
      "NAME_FROM_SEO_LIST"
    ]
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creative-center/seo/detail?biz_type=hashtag&names=NAME_FROM_SEO_LIST" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/creative-center/seo/detail",
    params={
        "biz_type": "hashtag",
        "names": ["NAME_FROM_SEO_LIST"],
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  biz_type: "hashtag",
  names: "NAME_FROM_SEO_LIST",
});
const res = await fetch(`https://api.tokconnect.com/v1/creative-center/seo/detail?${params}`, {
  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

No recorded example for this route yet. A success uses the usual envelope: the route's JSON under `data`, `next_cursor` when there is another page, and `meta` with the credits charged. See [pagination](https://tokconnect.com/docs/api/pagination/).

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Trending videos by market with engagement](https://tokconnect.com/docs/api/creative-center/#get-creative-center-top-videos)

`GET /v1/creative-center/top-videos`

1 credit per call

#### Parameters

- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

**5 more optional parameters**

- `country` (string): US (default), JP, VN, TH or ID.
- `page` (integer): Page 1-25.
- `period` (string): Week (default), day or long. **One of** `week` `day` `long`.
- `period_end` (integer): Unix seconds for the ranking close; 0 = last Sunday.
- `sort` (string): Views (default), engagement or `six_seconds_vtr`. **One of** `views` `engagement` `six_seconds_vtr`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creative_center` tool with `method: top_videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creative_center",
  "arguments": {
    "method": "top_videos",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creative-center/top-videos?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/creative-center/top-videos?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJwYWdlIjoyfQ",
    "videos": [
      {
        "caption": "プロ達の評価が恐ろしく高い プリュスオーから新作がでた plus eau（プリュスオー） リポルムシャンプー・トリートメント　各1,650円（税込） 全国のドラッグストア・バラエティストア等で販売中！ #PR #pluseau #シャンプー…",
        "engagementRate": 0.00048087144629807885,
        "handle": "yuya.koyama",
        "id": "7694996589001248021",
        "nickname": "こやゆう【美髪アドバイザー】",
        "posted": "2026-10-10T11:16:58Z",
        "url": "https://www.tiktok.com/@yuya.koyama/video/7694996589001248021",
        "views": 5893467
      },
      {
        "caption": "友達の様子が突然変わったらみんなはどうする？？💖好きな人ができたのかな？とか色々考えちゃうよね！ 鼻の黒ずみ*で悩んでいるならクレンジングはパーフェクトワンフォーカスの黒バームが推し🎶リニューアル前も…",
        "engagementRate": 0.00901324900435645,
        "handle": "maipan_03",
        "id": "7698310710845115668",
        "nickname": "まいぱん🍞",
        "posted": "2026-10-19T09:37:26Z",
        "url": "https://www.tiktok.com/@maipan_03/video/7698310710845115668",
        "views": 5766622
      },
      {
        "caption": "この主人公、不気味すぎる... #PR #ハズカシゲーム #LINEマンガ #無料マンガ",
        "engagementRate": 0.002261597480148014,
        "handle": "motsumotsu_manga",
        "id": "7694498082603552021",
        "nickname": "もつもつ🍆漫画紹介のひと",
        "posted": "2026-10-09T03:02:30Z",
        "url": "https://www.tiktok.com/@motsumotsu_manga/video/7694498082603552021",
        "views": 5078711
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyfQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].engagementRate`number
- `data.videos[].handle`string
- `data.videos[].id`string
- `data.videos[].nickname`string
- `data.videos[].posted`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Creative Partner agencies for a market](https://tokconnect.com/docs/api/creative-center/#get-creative-center-partners)

`GET /v1/creative-center/partners`

1 credit per call

#### Parameters

- `country` (string): Market code from [`GET /v1/reference/creative-markets`](https://tokconnect.com/docs/api/reference-lists/#get-reference-creative-markets), for example TH (default US, where TikTok lists no partners).

**1 more optional parameter**

- `query_date` (string): Unix timestamp from [`GET /v1/reference/creative-markets`](https://tokconnect.com/docs/api/reference-lists/#get-reference-creative-markets).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creative_center` tool with `method: partners`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creative_center",
  "arguments": {
    "method": "partners",
    "country": "US"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creative-center/partners?country=US" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  country: "US",
});
const res = await fetch(`https://api.tokconnect.com/v1/creative-center/partners?${params}`, {
  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 (this capture matched nothing):

```json
{
  "data": {
    "partners": []
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.partners`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Public SEO inspiration names by type](https://tokconnect.com/docs/api/creative-center/#get-creative-center-seo)

`GET /v1/creative-center/seo`

1 credit per call

#### Parameters

- `biz_type` (string): Which list. **One of** `keyword` `hashtag` `selling_points` `top_content` `top_ads`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `creative_center` tool with `method: seo_list`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "creative_center",
  "arguments": {
    "method": "seo_list",
    "biz_type": "keyword"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/creative-center/seo?biz_type=keyword" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  biz_type: "keyword",
});
const res = await fetch(`https://api.tokconnect.com/v1/creative-center/seo?${params}`, {
  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 (this capture matched nothing):

```json
{
  "data": {
    "names": [],
    "updated": "2026-10-30T00:00:00Z"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.names`array
- `data.updated`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/creative-center/

---

# TikTok charts API

TikTok's own leaderboards: the music charts, trending hashtags and searches, LIVE leaders and the top videos by market.

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

Call these routes with your own key, or ask the same question in plain words.

[Get an API key](https://app.tokconnect.com/api-key)[Ask about trending sounds](https://app.tokconnect.com/?q=Which%20TikTok%20sounds%20are%20trending%20right%20now%3F)

## Common parameters

These read the same on the routes below that take them.

- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## TikTok charts

Five leaderboards, one route each.

| Route | Returns | Limits |
|---|---|---|
| `GET /v1/charts/sounds` | The music chart: Top 50 or Viral 50 (TikTok's chart, not per market) | Up to 50 per page |
| `GET /v1/charts/hashtags` | Trending hashtags in a market over 7, 30 or 90 days, with posts, views and a daily popularity curve | Up to 50; empty for PL, NL and IE |
| `GET /v1/charts/searches` | Trending search phrases TikTok's website shows | Up to 100 |
| `GET /v1/charts/live` | TikTok's LIVE leaderboard (daily gifts or LIVE sales), as TikTok's app serves it; not per market | Up to 100 |
| `GET /v1/charts/videos` | Yesterday's top 100 videos in a market with views, organic views, engagement rate and 6-second view rate | Up to 100; TikTok has this list for US, JP, TH, ID and VN, other markets come back empty |

### [Trending hashtags in a market (7, 30 or 90 days)](https://tokconnect.com/docs/api/charts/#get-charts-hashtags)

`GET /v1/charts/hashtags`

1 credit per call · Paged · 14 of 17 markets

#### Parameters

- `limit` (integer): Results per page. Max 50. Values above the maximum are lowered and reported in notes.

**2 more optional parameters**

- `period` (string): Window in days: 7 (default), 30 or 90. **One of** `7` `30` `90`.
- `region` (string): Market: one of US, GB, DE, FR, ES, JP, TH, VN, ID, MY, PH, BR, MX, PL, IT, NL, IE (default US).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `charts` tool with `method: hashtags`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "charts",
  "arguments": {
    "method": "hashtags",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/charts/hashtags?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/charts/hashtags?${params}`, {
  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:

```json
{
  "data": {
    "as_of": "2026-10-15",
    "count": 3,
    "has_more": true,
    "items": [
      {
        "id": "7691443554018656263",
        "name": "tiktokscaryhorrorcontest",
        "popularity": [
          [
            "2026-10-09",
            0
          ],
          [
            "2026-10-10",
            49.96
          ]
        ],
        "posts": 73462,
        "rank": 1,
        "top_creators": [
          {
            "country": "US",
            "followers": 116246,
            "handle": "creator_1"
          },
          {
            "country": "US",
            "followers": 19261,
            "handle": "creator_2"
          }
        ],
        "views": 312182870
      },
      {
        "id": "7462773581512966150",
        "industry_ids": [
          25000000000
        ],
        "name": "marvelrivalsavengers",
        "popularity": [
          [
            "2026-10-09",
            95.543
          ],
          [
            "2026-10-10",
            100
          ]
        ],
        "posts": 110088,
        "rank": 2,
        "top_creators": [
          {
            "country": "US",
            "followers": 7222,
            "handle": "creator_4"
          },
          {
            "country": "US",
            "followers": 16364,
            "handle": "creator_5"
          }
        ],
        "views": 24120743
      }
    ],
    "market": "US",
    "next": "eyJwYWdlIjoyfQ",
    "notes": [
      "posts and views are TikTok's counts for the period. popularity is TikTok's daily index, [date, value], 100 = the hashtag's peak in the period.",
      "TikTok's period ends 2026-10-15 (its trending-hashtag data runs behind today)."
    ],
    "period_days": 7,
    "see_also": [
      "hashtag_search keyword=<items[].name>"
    ],
    "total": 100
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyfQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.count`integer
- `data.has_more`boolean
- `data.items`array
- `data.items[].id`string
- `data.items[].name`string
- `data.items[].popularity`array
- `data.items[].posts`integer
- `data.items[].rank`integer
- `data.items[].top_creators`array
- `data.items[].top_creators[].country`string
- `data.items[].top_creators[].followers`integer
- `data.items[].top_creators[].handle`string
- `data.items[].views`integer
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.period_days`integer
- `data.see_also`array
- `data.source`string
- `data.total`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [LIVE leaderboard (daily gifts or sales)](https://tokconnect.com/docs/api/charts/#get-charts-live)

`GET /v1/charts/live`

1 credit per call · Paged · Global chart

#### Parameters

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `board` (string): Daily (gift points today, default) or sales (LIVE sales leaderboard). **One of** `daily` `sales`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `charts` tool with `method: live`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "charts",
  "arguments": {
    "method": "live",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/charts/live?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/charts/live?${params}`, {
  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:

```json
{
  "data": {
    "as_of": "2026-10-30T23:27:15Z",
    "board": "daily",
    "count": 3,
    "has_more": false,
    "items": [
      {
        "followers": 10838,
        "handle": "creator_1",
        "nickname": "Example creator 1",
        "rank": 1,
        "score": 5388066
      },
      {
        "followers": 1077302,
        "handle": "creator_2",
        "nickname": "Example creator 2",
        "rank": 2,
        "score": 3012043
      },
      {
        "followers": 12567,
        "handle": "creator_3",
        "nickname": "Example creator 3",
        "rank": 3,
        "score": 1705220
      }
    ],
    "market": "as TikTok's app serves it (not per market)",
    "notes": [
      "score is the creator's gift points on TikTok's daily LIVE leaderboard.",
      "room_id is present only while the creator is LIVE."
    ],
    "resets_at": "2026-10-31T04:00:00Z",
    "see_also": [
      "creator id=@<items[].handle>",
      "live id=<items[].room_id>"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.board`string
- `data.count`integer
- `data.has_more`boolean
- `data.items`array
- `data.items[].followers`integer
- `data.items[].handle`string
- `data.items[].nickname`string
- `data.items[].rank`integer
- `data.items[].score`integer
- `data.items[].user_id`string
- `data.market`string
- `data.notes`array
- `data.resets_at`string
- `data.see_also`array
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Trending search phrases](https://tokconnect.com/docs/api/charts/#get-charts-searches)

`GET /v1/charts/searches`

1 credit per call · Paged

#### Parameters

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `charts` tool with `method: searches`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "charts",
  "arguments": {
    "method": "searches",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/charts/searches?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/charts/searches?${params}`, {
  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:

```json
{
  "data": {
    "as_of": "2026-10-30T23:28:14Z",
    "count": 3,
    "has_more": true,
    "items": [
      {
        "phrase": "Hyena makeup for Halloween trend",
        "rank": 1
      },
      {
        "phrase": "Waddup My Dawg meme trend",
        "rank": 2
      },
      {
        "phrase": "Fancy Footwork trend",
        "rank": 3
      }
    ],
    "market": "TikTok website (not per market)",
    "notes": [
      "Phrases in the order TikTok's website lists them. They are not search volumes; use demand_find_topics for volume."
    ],
    "see_also": [
      "demand_find_topics keyword=<items[].phrase>",
      "video_search keyword=<items[].phrase>"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.count`integer
- `data.has_more`boolean
- `data.items`array
- `data.items[].phrase`string
- `data.items[].rank`integer
- `data.market`string
- `data.notes`array
- `data.see_also`array
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [TikTok's music chart (Top 50 or Viral 50)](https://tokconnect.com/docs/api/charts/#get-charts-sounds)

`GET /v1/charts/sounds`

1 credit per call · Paged · Global chart

#### Parameters

- `limit` (integer): Results per page. Max 50. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `chart` (string): Top (Top 50, default) or viral (Viral 50). **One of** `top` `viral`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `charts` tool with `method: sounds`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "charts",
  "arguments": {
    "method": "sounds",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/charts/sounds?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/charts/sounds?${params}`, {
  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:

```json
{
  "data": {
    "as_of": "2026-10-29",
    "chart": "top",
    "count": 3,
    "has_more": true,
    "items": [
      {
        "album": "Kiss All The Time. Disco, Occasionally.",
        "author": "Harry Styles",
        "cleared_for_business": true,
        "duration": 60,
        "id": "7613798254214187009",
        "original": false,
        "rank": 1,
        "release_date": "2026-03-06",
        "title": "Coming Up Roses",
        "trend": 4,
        "videos": 209442
      },
      {
        "album": "Housewife",
        "author": "Tate McRae",
        "cleared_for_business": true,
        "duration": 36,
        "id": "7697010651306838068",
        "original": false,
        "rank": 2,
        "release_date": "2026-10-15",
        "title": "Housewife",
        "trend": 4,
        "videos": 401171
      },
      {
        "album": "Metropolitan",
        "author": "Nova Charisma",
        "cleared_for_business": true,
        "duration": 60,
        "id": "7370364561877321729",
        "original": false,
        "rank": 3,
        "title": "Stolen From Each Other",
        "trend": 4,
        "videos": 8479
      }
    ],
    "market": "TikTok chart (not per market)",
    "next": "eyJvZmZzZXQiOjN9",
    "notes": [
      "videos is TikTok's count of posts using the sound. cleared_for_business is TikTok's commercial-music flag. trend is TikTok's rank-movement code for the entry, passed on as TikTok sends it."
    ],
    "see_also": [
      "sound method=videos id=<items[].id>"
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJvZmZzZXQiOjN9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.chart`string
- `data.count`integer
- `data.has_more`boolean
- `data.items`array
- `data.items[].album`string
- `data.items[].author`string
- `data.items[].cleared_for_business`boolean
- `data.items[].duration`integer
- `data.items[].id`string
- `data.items[].original`boolean
- `data.items[].rank`integer
- `data.items[].release_date`string
- `data.items[].title`string
- `data.items[].trend`integer
- `data.items[].videos`integer
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.see_also`array
- `data.source`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Yesterday's top 100 videos in a market](https://tokconnect.com/docs/api/charts/#get-charts-videos)

`GET /v1/charts/videos`

1 credit per call · Paged · 5 markets: US, JP, TH, ID, VN

#### Parameters

- `limit` (integer): Results per page. Max 100. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `region` (string): Market: one of US, GB, DE, FR, ES, JP, TH, VN, ID, MY, PH, BR, MX, PL, IT, NL, IE (default US).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `charts` tool with `method: videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "charts",
  "arguments": {
    "method": "videos",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/charts/videos?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/charts/videos?${params}`, {
  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:

```json
{
  "data": {
    "as_of": "2026-10-29",
    "count": 3,
    "has_more": true,
    "items": [
      {
        "cover": "(signed media URL)",
        "created": "2026-09-10",
        "engagement_rate": 0.001279374872518347,
        "followers": 17082381,
        "handle": "creator_1",
        "id": "7684011124739656991",
        "nickname": "Example creator 1",
        "organic_views": 1898401,
        "rank": 1,
        "six_second_view_rate": 0.02428703324049609,
        "views": 32906696
      },
      {
        "cover": "(signed media URL)",
        "created": "2026-08-26",
        "engagement_rate": 0.0018894018055804198,
        "followers": 250572,
        "handle": "creator_2",
        "id": "7678479724896587038",
        "nickname": "Example creator 2",
        "organic_views": 2735418,
        "rank": 2,
        "six_second_view_rate": 0.0342646857694568,
        "views": 31280800
      },
      {
        "cover": "(signed media URL)",
        "created": "2026-09-17",
        "engagement_rate": 0.0005375644554008684,
        "followers": 75381,
        "handle": "creator_3",
        "id": "7686545222628658446",
        "nickname": "Example creator 3",
        "organic_views": 446268,
        "rank": 3,
        "six_second_view_rate": 0.011719839544846095,
        "views": 24601701
      }
    ],
    "market": "US",
    "next": "eyJwYWdlIjoyfQ",
    "notes": [
      "TikTok's daily top-videos list for US, day ending 2026-10-29 UTC. views and organic_views are for that day; rates are fractions (0.012 = 1.2%)."
    ],
    "see_also": [
      "video id=<items[].id>"
    ],
    "total": 100
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJwYWdlIjoyfQ"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.as_of`string
- `data.count`integer
- `data.has_more`boolean
- `data.items`array
- `data.items[].cover`string
- `data.items[].created`string
- `data.items[].engagement_rate`number
- `data.items[].followers`integer
- `data.items[].handle`string
- `data.items[].id`string
- `data.items[].nickname`string
- `data.items[].organic_views`integer
- `data.items[].rank`integer
- `data.items[].six_second_view_rate`number
- `data.items[].title`string
- `data.items[].views`integer
- `data.market`string
- `data.next`string
- `data.notes`array
- `data.see_also`array
- `data.source`string
- `data.total`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/charts/

---

# TikTok sounds, hashtags and places API

Sounds, hashtags and tagged places, each with the videos that use it. Music marketers check a sound before they post; restaurants check the videos tagged at their address.

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

Call these routes with your own key, or ask the same question in plain words.

[Get an API key](https://app.tokconnect.com/api-key)[Ask it in plain words](https://app.tokconnect.com/?q=Which%20sounds%20are%20hot%20on%20TikTok%20right%20now%20and%20which%20hashtags%20do%20skincare%20videos%20use)[Free sound checker](https://tokconnect.com/tools/tiktok-sound-checker/)[Free hashtag finder](https://tokconnect.com/tools/tiktok-hashtag-finder/)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/search/sounds`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-search-sounds) | Sounds matching keyword |
| [GET `/v1/sounds/beats`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-sounds-beats) | Recommended beats |
| [GET `/v1/sounds/hot`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-sounds-hot) | Currently hot original sounds |
| [GET `/v1/sounds/licensed`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-sounds-licensed) | Licensed tracks cleared for use |
| [GET `/v1/sounds/{id}`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-sounds-id) | Title, author, duration, original or licensed, post count |
| [GET `/v1/sounds/{id}/videos`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-sounds-id-videos) | Videos using the sound |
| [GET `/v1/hashtags/{id}`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-hashtags-id) | Views, video count, description |
| [GET `/v1/hashtags/{id}/related`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-hashtags-id-related) | Hashtags TikTok relates to it |
| [GET `/v1/hashtags/{id}/videos`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-hashtags-id-videos) | Videos using the hashtag |
| [GET `/v1/places/{id}`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-places-id) | Name, category, address, tagged video count |
| [GET `/v1/places/{id}/reviews`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-places-id-reviews) | Public reviews with stars, text and photos |
| [GET `/v1/places/{id}/videos`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-places-id-videos) | Videos tagged at the place |

## Common parameters

These read the same on the routes below that take them.

- `region` (string): Market as an ISO country code, default US. Amounts are in the market's currency. See [Markets](https://tokconnect.com/docs/api/markets/).
- `cursor` (string): Paging: pass `next_cursor` from the previous response unchanged. Omit on the first page.
- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## Find sounds

Find TikTok sounds by keyword, or list TikTok's hot sounds, beats and licensed music. Pass a sound id to the sound routes for its videos. Find hashtags and places by keyword on the [Search page](https://tokconnect.com/docs/api/search/#get-search-hashtags).

### [Sounds matching keyword](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-search-sounds)

`GET /v1/search/sounds`

1 credit per call · Paged · 17 markets

#### Parameters

- `keyword` (string): Search phrase.
- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `sound_search` tool with `method: keyword`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "sound_search",
  "arguments": {
    "method": "keyword",
    "keyword": "lip oil",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/search/sounds?keyword=lip%20oil&limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

r = requests.get(
    "https://api.tokconnect.com/v1/search/sounds",
    params={
        "keyword": "lip oil",
        "limit": 3,
    },
    headers={"X-API-Key": os.environ["TOKCONNECT_API_KEY"]},
    timeout=100,
)
r.raise_for_status()
body = r.json()
print(body["data"])
```

```javascript
const params = new URLSearchParams({
  keyword: "lip oil",
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/search/sounds?${params}`, {
  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:

```json
{
  "data": {
    "feedback_type": "music",
    "hasMore": true,
    "next": "eyJjdXJzb3IiOjMsInNlYXJjaF9pZCI6InUuMjAyNjEwMzAyMzI2NDdGNjcxQUI5OTlGOTQ1MjRCNzNEQyJ9",
    "qc": "",
    "search_id": "u.20261030232647F671AB999F94524B73DC",
    "sounds": [
      {
        "album": "INTRAVENOSA",
        "author": "Mellysa Catty & xTurbo",
        "durationSec": 16,
        "id": "7551425165536643088",
        "title": "Lip Oil",
        "url": "https://www.tiktok.com/music/-7551425165536643088",
        "videos": 2
      },
      {
        "author": "Lipi",
        "commercialUse": true,
        "durationSec": 15,
        "id": "7379968945522739984",
        "original": true,
        "title": "original sound - tahaminalipi",
        "url": "https://www.tiktok.com/music/-7379968945522739984",
        "videos": 12373
      },
      {
        "album": "Forever with You",
        "author": "SebaLazi",
        "durationSec": 60,
        "id": "7478886011436894225",
        "title": "Lipsi",
        "url": "https://www.tiktok.com/music/-7478886011436894225",
        "videos": 676
      }
    ],
    "version": "v2"
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOjMsInNlYXJjaF9pZCI6InUuMjAyNjEwMzAyMzI2NDdGNjcxQUI5OTlGOTQ1MjRCNzNEQyJ9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.feedback_type`string
- `data.hasMore`boolean
- `data.next`string
- `data.qc`string
- `data.search_id`string
- `data.sounds`array
- `data.sounds[].album`string
- `data.sounds[].author`string
- `data.sounds[].durationSec`integer
- `data.sounds[].id`string
- `data.sounds[].title`string
- `data.sounds[].url`string
- `data.sounds[].videos`integer
- `data.version`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Recommended beats](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-sounds-beats)

`GET /v1/sounds/beats`

1 credit per call · Paged

#### Parameters

- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `sound_search` tool with `method: beats`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "sound_search",
  "arguments": {
    "method": "beats",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/sounds/beats?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/sounds/beats?${params}`, {
  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:

```json
{
  "data": {
    "from_recommend": true,
    "hasMore": false,
    "sounds": [
      {
        "album": "Cute",
        "author": "CLOUDEE",
        "commercialUse": true,
        "durationSec": 60,
        "id": "7284220358223005697",
        "title": "Cute",
        "url": "https://www.tiktok.com/music/-7284220358223005697",
        "videos": 577480
      },
      {
        "author": "Stacey🦋",
        "commercialUse": true,
        "durationSec": 35,
        "id": "7702366598140676886",
        "original": true,
        "title": "original sound - stacey.shops",
        "url": "https://www.tiktok.com/music/-7702366598140676886",
        "videos": 1
      },
      {
        "author": "Eirini ✨",
        "commercialUse": true,
        "durationSec": 7,
        "id": "7702130662115166979",
        "original": true,
        "title": "original sound - _eirinikatsigianni",
        "url": "https://www.tiktok.com/music/-7702130662115166979"
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.from_recommend`boolean
- `data.hasMore`boolean
- `data.sounds`array
- `data.sounds[].album`string
- `data.sounds[].author`string
- `data.sounds[].commercialUse`boolean
- `data.sounds[].durationSec`integer
- `data.sounds[].id`string
- `data.sounds[].title`string
- `data.sounds[].url`string
- `data.sounds[].videos`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Currently hot original sounds](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-sounds-hot)

`GET /v1/sounds/hot`

1 credit per call · Paged

#### Parameters

- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `sound_search` tool with `method: hot`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "sound_search",
  "arguments": {
    "method": "hot",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/sounds/hot?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/sounds/hot?${params}`, {
  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:

```json
{
  "data": {
    "from_recommend": true,
    "hasMore": true,
    "next": "eyJjdXJzb3IiOjN9",
    "sounds": [
      {
        "album": "Cute",
        "author": "CLOUDEE",
        "commercialUse": true,
        "durationSec": 60,
        "id": "7284220358223005697",
        "title": "Cute",
        "url": "https://www.tiktok.com/music/-7284220358223005697",
        "videos": 577480
      },
      {
        "author": "naran sitaula",
        "commercialUse": true,
        "durationSec": 21,
        "id": "7702238644861553411",
        "original": true,
        "title": "original sound - naran.sitaula",
        "url": "https://www.tiktok.com/music/-7702238644861553411",
        "videos": 1
      },
      {
        "album": "Do Not Give Up Easily",
        "author": "Gareta Johan",
        "durationSec": 45,
        "id": "7609944367696906257",
        "title": "Do Not Give Up Easily",
        "url": "https://www.tiktok.com/music/-7609944367696906257",
        "videos": 19337
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOjN9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.from_recommend`boolean
- `data.hasMore`boolean
- `data.next`string
- `data.sounds`array
- `data.sounds[].album`string
- `data.sounds[].author`string
- `data.sounds[].commercialUse`boolean
- `data.sounds[].durationSec`integer
- `data.sounds[].id`string
- `data.sounds[].title`string
- `data.sounds[].url`string
- `data.sounds[].videos`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Licensed tracks cleared for use](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-sounds-licensed)

`GET /v1/sounds/licensed`

1 credit per call · Paged

#### Parameters

- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `sound_search` tool with `method: licensed`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "sound_search",
  "arguments": {
    "method": "licensed",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/sounds/licensed?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/sounds/licensed?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": false,
    "sounds": [
      {
        "author": "Galantis",
        "durationSec": 18,
        "id": "6575698583637461761",
        "title": "Love On Me",
        "url": "https://www.tiktok.com/music/-6575698583637461761",
        "videos": 1441190
      },
      {
        "album": "One Call Away",
        "author": "Charlie Puth",
        "durationSec": 41,
        "id": "6353936740163521282",
        "title": "One Call Away",
        "url": "https://www.tiktok.com/music/-6353936740163521282",
        "videos": 3602251
      },
      {
        "album": "SQUARE UP",
        "author": "BLACKPINK",
        "durationSec": 18,
        "id": "6569011430538873607",
        "original": true,
        "title": "Forever Young",
        "url": "https://www.tiktok.com/music/-6569011430538873607",
        "videos": 704647
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.sounds`array
- `data.sounds[].author`string
- `data.sounds[].durationSec`integer
- `data.sounds[].id`string
- `data.sounds[].title`string
- `data.sounds[].url`string
- `data.sounds[].videos`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## One sound

One TikTok sound (id = sound id from any post or from [`GET /v1/search/sounds`](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-search-sounds), or a sound link): detail or the videos using it.

### [Title, author, duration, original or licensed, post count](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-sounds-id)

`GET /v1/sounds/{id}`

1 credit per call

#### Parameters

- `id` (string, path, required): Sound id (sound.id on a post) or a TikTok sound link.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `sound` tool with `method: detail`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "sound",
  "arguments": {
    "method": "detail",
    "id": "7139362230881094442"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/sounds/7139362230881094442" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/sounds/7139362230881094442", {
  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:

```json
{
  "data": {
    "author": "JERI",
    "commercialUse": true,
    "durationSec": 40,
    "id": "7139362230881094442",
    "original": true,
    "title": "ariana grande . ill do it",
    "url": "https://www.tiktok.com/music/-7139362230881094442",
    "videos": 37373
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.author`string
- `data.commercialUse`boolean
- `data.durationSec`integer
- `data.id`string
- `data.original`boolean
- `data.title`string
- `data.url`string
- `data.videos`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Videos using the sound](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-sounds-id-videos)

`GET /v1/sounds/{id}/videos`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Sound id (sound.id on a post) or a TikTok sound link.
- `limit` (integer): Results per page. Max 50. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `sound` tool with `method: videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "sound",
  "arguments": {
    "method": "videos",
    "id": "7139362230881094442",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/sounds/7139362230881094442/videos?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/sounds/7139362230881094442/videos?${params}`, {
  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:

```json
{
  "data": {
    "can_pin_video": false,
    "hasMore": true,
    "need_lazy_loading": false,
    "next": "eyJjdXJzb3IiOiIxMiJ9",
    "version": "v2",
    "videos": [
      {
        "caption": "ariana grande - ill do it x the light is coming #arianator #ariana #heidimontag #music #fyp #remix #mashup",
        "comments": 334,
        "creator": {
          "handle": "princesstar101",
          "id": "6546365462278575104",
          "nickname": "JERI",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 41.12,
        "hashtags": [
          {
            "id": "28006",
            "name": "arianator"
          },
          {
            "id": "12326",
            "name": "ariana"
          }
        ],
        "id": "7139362264565501226",
        "language": "en",
        "likes": 30956,
        "posted": "2022-09-04T03:31:54Z",
        "saves": 16384,
        "shares": 683,
        "sound": {
          "author": "JERI",
          "id": "7139362230881094442",
          "original": true,
          "title": "ariana grande . ill do it"
        },
        "url": "https://www.tiktok.com/@princesstar101/video/7139362264565501226",
        "views": 673675
      },
      {
        "caption": "Amber is the best",
        "comments": 187,
        "creator": {
          "handle": "heidimontag",
          "id": "114703556082917376",
          "nickname": "heidimontag",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 13.258,
        "id": "6896945616031632646",
        "language": "en",
        "likes": 6166,
        "posted": "2020-11-19T21:12:05Z",
        "saves": 1387,
        "shares": 106,
        "sound": {
          "author": "Heidi Montag",
          "id": "238606941294632960",
          "title": "I'll Do It"
        },
        "url": "https://www.tiktok.com/@heidimontag/video/6896945616031632646",
        "views": 507712
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOiIxMiJ9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.can_pin_video`boolean
- `data.hasMore`boolean
- `data.need_lazy_loading`boolean
- `data.next`string
- `data.version`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].durationSec`number
- `data.videos[].hashtags`array
- `data.videos[].hashtags[].id`string
- `data.videos[].hashtags[].name`string
- `data.videos[].id`string
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.original`boolean
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## One hashtag

One hashtag (id from [`GET /v1/search/hashtags`](https://tokconnect.com/docs/api/search/#get-search-hashtags) or `hashtags[].id` on a post): detail, its videos (hot or newest), or related hashtags.

### [Views, video count, description](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-hashtags-id)

`GET /v1/hashtags/{id}`

1 credit per call · 17 markets

#### Parameters

- `id` (string, path, required): Hashtag id (`hashtags[].id`).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `hashtag` tool with `method: detail`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "hashtag",
  "arguments": {
    "method": "detail",
    "id": "504245"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/hashtags/504245" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/hashtags/504245", {
  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:

```json
{
  "data": {
    "description": "From routines to glow ups, discover how the skincare community on TikTok keeps their skin cared for.",
    "id": "504245",
    "name": "SkinCare",
    "url": "https://www.tiktok.com/tag/SkinCare",
    "videos": 62776858,
    "views": 1002857221064
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.description`string
- `data.id`string
- `data.name`string
- `data.url`string
- `data.videos`integer
- `data.views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Hashtags TikTok relates to it](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-hashtags-id-related)

`GET /v1/hashtags/{id}/related`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Hashtag id (`hashtags[].id`).
- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `hashtag` tool with `method: related`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "hashtag",
  "arguments": {
    "method": "related",
    "id": "504245",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/hashtags/504245/related?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/hashtags/504245/related?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": false,
    "hashtags": [
      {
        "id": "55253017",
        "name": "skincareproducts",
        "url": "https://www.tiktok.com/tag/skincareproducts",
        "videos": 1728190,
        "views": 22631704765
      },
      {
        "id": "7024790",
        "name": "skin_care",
        "url": "https://www.tiktok.com/tag/skin_care",
        "videos": 33779,
        "views": 481670171
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.hashtags`array
- `data.hashtags[].id`string
- `data.hashtags[].name`string
- `data.hashtags[].url`string
- `data.hashtags[].videos`integer
- `data.hashtags[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Videos using the hashtag](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-hashtags-id-videos)

`GET /v1/hashtags/{id}/videos`

1 credit per call · Paged · 17 markets

#### Parameters

- `id` (string, path, required): Hashtag id (`hashtags[].id`).
- `limit` (integer): Results per page. Max 50. Values above the maximum are lowered and reported in notes.

**1 more optional parameter**

- `sort` (string): Hot (TikTok's ranking, default) or newest. **One of** `hot` `newest`.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `hashtag` tool with `method: videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "hashtag",
  "arguments": {
    "method": "videos",
    "id": "504245",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/hashtags/504245/videos?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/hashtags/504245/videos?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJjdXJzb3IiOjN9",
    "videos": [
      {
        "caption": "4 Step Beginner Skincare routine 🌸✨ #skincare #beginnerskincareroutine #skincaretipsforeveryone #blackgirlskincare",
        "comments": 1155,
        "creator": {
          "handle": "mayriahm.a",
          "id": "6532038966940549121",
          "nickname": "Mariam 🤍",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 44.534,
        "hashtags": [
          {
            "id": "504245",
            "name": "SkinCare"
          },
          {
            "id": "1690942436043778",
            "name": "beginnerskincareroutine"
          }
        ],
        "id": "7107330561206734086",
        "language": "en",
        "likes": 140759,
        "posted": "2022-06-09T19:52:32Z",
        "saves": 58342,
        "shares": 3536,
        "sound": {
          "author": "Burna Boy",
          "id": "7096289813334083585",
          "title": "Last Last"
        },
        "url": "https://www.tiktok.com/@mayriahm.a/video/7107330561206734086",
        "views": 4340166
      },
      {
        "caption": "The fact it doesn’t sting her eyes 😭 i need #kylie #kyliejenner #skincare",
        "comments": 98,
        "creator": {
          "handle": "koreababe1",
          "id": "6981218295518299137",
          "nickname": "Korea Babe",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 7.151,
        "hashtags": [
          {
            "id": "23295",
            "name": "kylie"
          },
          {
            "id": "18830",
            "name": "kyliejenner"
          }
        ],
        "id": "7692712348200504583",
        "language": "en",
        "likes": 57559,
        "posted": "2026-10-04T07:32:52Z",
        "saves": 8792,
        "shares": 728,
        "sound": {
          "author": "ℳ𝒶𝓃𝓊 🪽",
          "id": "7596069087663459084",
          "original": true,
          "title": "MONTAGEM ALQUIMIA"
        },
        "url": "https://www.tiktok.com/@koreababe1/video/7692712348200504583",
        "views": 1296455
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOjN9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].creator.verified`boolean
- `data.videos[].durationSec`number
- `data.videos[].hashtags`array
- `data.videos[].hashtags[].id`string
- `data.videos[].hashtags[].name`string
- `data.videos[].id`string
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## One place

One tagged place: business, venue or landmark (id from [`GET /v1/search/places`](https://tokconnect.com/docs/api/search/#get-search-places), a post's place.id, or a place link): detail, videos tagged there, or TikTok's public reviews.

### [Name, category, address, tagged video count](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-places-id)

`GET /v1/places/{id}`

1 credit per call

#### Parameters

- `id` (string, path, required): Place id (place.id on a post, or from [`GET /v1/search/places`](https://tokconnect.com/docs/api/search/#get-search-places)) or a place link.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `place` tool with `method: detail`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "place",
  "arguments": {
    "method": "detail",
    "id": "42203860535857971"
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/places/42203860535857971" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const res = await fetch("https://api.tokconnect.com/v1/places/42203860535857971", {
  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

The recorded example for this route is not shown on a public page. This is its shape: field names and types, no values.

Response shape:

```json
{
  "data": {
    "address": "string",
    "category": "string",
    "city": "string",
    "hours": "string",
    "id": "string",
    "name": "string",
    "rating": "number",
    "reviews": "number",
    "url": "string",
    "videos": "number"
  },
  "meta": {
    "credits_charged": "number",
    "credits_remaining": "number",
    "request_id": "string"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.address`string
- `data.category`string
- `data.city`string
- `data.hours`string
- `data.id`string
- `data.name`string
- `data.rating`integer
- `data.reviews`integer
- `data.url`string
- `data.videos`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Public reviews with stars, text and photos](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-places-id-reviews)

`GET /v1/places/{id}/reviews`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Place id (place.id on a post, or from [`GET /v1/search/places`](https://tokconnect.com/docs/api/search/#get-search-places)) or a place link.
- `limit` (integer): Results per page. Max 20. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `place` tool with `method: reviews`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "place",
  "arguments": {
    "method": "reviews",
    "id": "42203860535857971",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/places/42203860535857971/reviews?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/places/42203860535857971/reviews?${params}`, {
  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

The recorded example for this route is not shown on a public page. This is its shape: field names and types, no values.

Response shape:

```json
{
  "data": {
    "hasMore": "boolean",
    "next": "string",
    "place": "string",
    "reviews": [
      {
        "id": "string",
        "language": "string",
        "posted": "string",
        "rating": "number",
        "reviewer": "string",
        "text": "string"
      }
    ],
    "score": "number",
    "scoreLabel": "string",
    "totalReviews": "number"
  },
  "meta": {
    "credits_charged": "number",
    "credits_remaining": "number",
    "request_id": "string"
  },
  "next_cursor": "string"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.place`string
- `data.reviews`array
- `data.reviews[].id`string
- `data.reviews[].language`string
- `data.reviews[].posted`string
- `data.reviews[].rating`integer
- `data.reviews[].reviewer`string
- `data.reviews[].text`string
- `data.score`integer
- `data.scoreLabel`string
- `data.totalReviews`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Videos tagged at the place](https://tokconnect.com/docs/api/sounds-hashtags-places/#get-places-id-videos)

`GET /v1/places/{id}/videos`

1 credit per call · Paged

#### Parameters

- `id` (string, path, required): Place id (place.id on a post, or from [`GET /v1/search/places`](https://tokconnect.com/docs/api/search/#get-search-places)) or a place link.
- `limit` (integer): Results per page. Max 30. Values above the maximum are lowered and reported in notes.

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `place` tool with `method: videos`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

```json
{
  "tool": "place",
  "arguments": {
    "method": "videos",
    "id": "42203860535857971",
    "limit": 3
  }
}
```

#### Request

```bash
curl "https://api.tokconnect.com/v1/places/42203860535857971/videos?limit=3" \
  -H "X-API-Key: $TOKCONNECT_API_KEY"
```

```python
import os
import requests

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

```javascript
const params = new URLSearchParams({
  limit: "3",
});
const res = await fetch(`https://api.tokconnect.com/v1/places/42203860535857971/videos?${params}`, {
  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:

```json
{
  "data": {
    "hasMore": true,
    "next": "eyJjdXJzb3IiOiIxNTkxNCJ9",
    "videos": [
      {
        "caption": "i really need some video ideas 😭#viral #foryou #xyzcba #bikelife #boyfriend",
        "comments": 125,
        "creator": {
          "followers": 2437,
          "handle": "skppy.x",
          "id": "6843364600545575942",
          "nickname": "pinda🦘🏍",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 10,
        "hashtags": [
          {
            "id": "20884",
            "name": "viral"
          },
          {
            "id": "42164",
            "name": "foryou"
          }
        ],
        "id": "7598997004211014944",
        "language": "en",
        "likes": 90300,
        "place": {
          "id": "42203860535857971",
          "name": "Coffeeshop Amsterdam"
        },
        "posted": "2026-01-24T18:29:40Z",
        "saves": 7251,
        "shares": 5526,
        "sound": {
          "author": "Aurora 💫",
          "id": "7135134965590657834",
          "original": true,
          "title": "original sound"
        },
        "url": "https://www.tiktok.com/@skppy.x/video/7598997004211014944",
        "views": 679400
      },
      {
        "caption": "lekkerste ontbijt in nederland  #fyp #viral #tosti  #antidepresivo #ontbijt",
        "comments": 119,
        "creator": {
          "followers": 6713,
          "handle": "kroketa.memes",
          "id": "7445298973416211488",
          "nickname": "kroketa memes",
          "secUid": "MS4wLjABAAAA…"
        },
        "durationSec": 7,
        "hashtags": [
          {
            "id": "229207",
            "name": "fyp"
          },
          {
            "id": "20884",
            "name": "viral"
          }
        ],
        "id": "7592287717405297952",
        "language": "nl",
        "likes": 49800,
        "place": {
          "id": "42203860535857971",
          "name": "Coffeeshop Amsterdam"
        },
        "posted": "2026-01-06T16:34:13Z",
        "saves": 6600,
        "shares": 19300,
        "sound": {
          "author": "kroketa memes",
          "id": "7592287775769070368",
          "original": true,
          "title": "origineel geluid"
        },
        "url": "https://www.tiktok.com/@kroketa.memes/video/7592287717405297952",
        "views": 643200
      }
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  },
  "next_cursor": "eyJjdXJzb3IiOiIxNTkxNCJ9"
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.hasMore`boolean
- `data.next`string
- `data.videos`array
- `data.videos[].caption`string
- `data.videos[].comments`integer
- `data.videos[].creator`object
- `data.videos[].creator.followers`integer
- `data.videos[].creator.handle`string
- `data.videos[].creator.id`string
- `data.videos[].creator.nickname`string
- `data.videos[].creator.secUid`string
- `data.videos[].durationSec`integer
- `data.videos[].hashtags`array
- `data.videos[].hashtags[].id`string
- `data.videos[].hashtags[].name`string
- `data.videos[].id`string
- `data.videos[].language`string
- `data.videos[].likes`integer
- `data.videos[].place`object
- `data.videos[].place.id`string
- `data.videos[].place.name`string
- `data.videos[].posted`string
- `data.videos[].saves`integer
- `data.videos[].shares`integer
- `data.videos[].sound`object
- `data.videos[].sound.author`string
- `data.videos[].sound.id`string
- `data.videos[].sound.original`boolean
- `data.videos[].sound.title`string
- `data.videos[].url`string
- `data.videos[].views`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/sounds-hashtags-places/

---

# TikTok Shop filters, category ids and gift prices API

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

Fetch these lists once and cache them. Each call costs 1 credit. Want gift prices as a table instead of JSON? See the [TikTok gift calculator](https://tokconnect.com/gifts/).

[Get an API key](https://app.tokconnect.com/api-key)

## Routes

| Route | Returns |
|---|---|
| [GET `/v1/markets`](https://tokconnect.com/docs/api/reference-lists/#get-markets) | The supported markets |
| [GET `/v1/reference/ad-regions`](https://tokconnect.com/docs/api/reference-lists/#get-reference-ad-regions) | EU/UK regions the Ad Library covers |
| [GET `/v1/reference/creative-markets`](https://tokconnect.com/docs/api/reference-lists/#get-reference-creative-markets) | Creative Partner markets and dates |
| [GET `/v1/reference/csi-channels`](https://tokconnect.com/docs/api/reference-lists/#get-reference-csi-channels) | Creator Search Insights channels and trending categories |
| [GET `/v1/reference/csi-languages`](https://tokconnect.com/docs/api/reference-lists/#get-reference-csi-languages) | Creator Search Insights language codes |
| [GET `/v1/reference/explore-categories`](https://tokconnect.com/docs/api/reference-lists/#get-reference-explore-categories) | Category ids for the Explore feed |
| [GET `/v1/reference/live-gifts`](https://tokconnect.com/docs/api/reference-lists/#get-reference-live-gifts) | LIVE gifts and their coin prices |
| [GET `/v1/reference/sales-filters`](https://tokconnect.com/docs/api/reference-lists/#get-reference-sales-filters) | Every Shop Analytics filter, its values and sort fields |

## Common parameters

These read the same on the routes below that take them.

- `detail` (string): compact (default) returns the useful fields; full adds the raw payload (large). **Default**`compact` **One of** `compact` `full`.

## Markets

[`GET /v1/markets`](https://tokconnect.com/docs/api/reference-lists/#get-markets) lists the 17 TikTok Shop markets with each one's currency, language and tier. The full table is on the [Markets](https://tokconnect.com/docs/api/markets/) page.

### [The supported markets](https://tokconnect.com/docs/api/reference-lists/#get-markets)

`GET /v1/markets`

1 credit per call

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/reference-lists/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `shop_regions` tool. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

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

#### Request

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

```python
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"])
```

```javascript
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:

```json
{
  "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. Other country codes are refused."
    ]
  },
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 7906,
    "request_id": "req_3f9c2a1b7d4e"
  }
}
```

**Response fields**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.count`integer
- `data.default`string
- `data.markets`array
- `data.markets[].code`string
- `data.markets[].currency`string
- `data.markets[].language`string
- `data.markets[].name`string
- `data.markets[].tier`string
- `data.notes`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

## Reference lists

Static lists other routes need: Creator Search Insights channels and categories and their language codes, Explore category ids, LIVE gift coin prices, Ad Library regions, Creative Partner markets, and the Shop Analytics filters and sort fields. These lists change rarely: fetch them once and cache them.

### [EU/UK regions the Ad Library covers](https://tokconnect.com/docs/api/reference-lists/#get-reference-ad-regions)

`GET /v1/reference/ad-regions`

1 credit per call

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/reference-lists/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `reference` tool with `method: ad_regions`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

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

#### Request

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

```python
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"])
```

```javascript
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:

```json
{
  "data": {
    "code": 0,
    "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**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.code`integer
- `data.regions`array
- `data.regions[].id`string
- `data.regions[].name`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Creative Partner markets and dates](https://tokconnect.com/docs/api/reference-lists/#get-reference-creative-markets)

`GET /v1/reference/creative-markets`

1 credit per call

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/reference-lists/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `reference` tool with `method: creative_markets`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

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

#### Request

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

```python
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"])
```

```javascript
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:

```json
{
  "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**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.countries`array
- `data.end`string
- `data.endUnix`integer
- `data.start`string
- `data.startUnix`integer
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Creator Search Insights channels and trending categories](https://tokconnect.com/docs/api/reference-lists/#get-reference-csi-channels)

`GET /v1/reference/csi-channels`

1 credit per call

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/reference-lists/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `reference` tool with `method: csi_channels`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

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

#### Request

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

```python
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"])
```

```javascript
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:

```json
{
  "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**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.channels`array
- `data.channels[].categories`array
- `data.channels[].channel_key`string
- `data.channels[].languages`array
- `data.channels[].name`string
- `data.channels[].tabDetails`array
- `data.channels[].tabDetails[].endpoint`string
- `data.channels[].tabDetails[].key`string
- `data.channels[].tabDetails[].name`string
- `data.channels[].tabDetails[].queryKey`string
- `data.channels[].tabs`array
- `data.trendingCategories`array
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Creator Search Insights language codes](https://tokconnect.com/docs/api/reference-lists/#get-reference-csi-languages)

`GET /v1/reference/csi-languages`

1 credit per call

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/reference-lists/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `reference` tool with `method: csi_languages`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

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

#### Request

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

```python
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"])
```

```javascript
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:

```json
{
  "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**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.languages`array
- `data.languages[].id`string
- `data.languages[].name`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Category ids for the Explore feed](https://tokconnect.com/docs/api/reference-lists/#get-reference-explore-categories)

`GET /v1/reference/explore-categories`

1 credit per call

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/reference-lists/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `reference` tool with `method: explore_categories`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

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

#### Request

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

```python
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"])
```

```javascript
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:

```json
{
  "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**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.categories`array
- `data.categories[].id`integer
- `data.categories[].name`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [LIVE gifts and their coin prices](https://tokconnect.com/docs/api/reference-lists/#get-reference-live-gifts)

`GET /v1/reference/live-gifts`

1 credit per call

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/reference-lists/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `reference` tool with `method: live_gifts`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

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

#### Request

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

```python
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"])
```

```javascript
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:

```json
{
  "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**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.gifts`array
- `data.gifts[].coins`integer
- `data.gifts[].combo`boolean
- `data.gifts[].id`string
- `data.gifts[].name`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

### [Every Shop Analytics filter, its values and sort fields](https://tokconnect.com/docs/api/reference-lists/#get-reference-sales-filters)

`GET /v1/reference/sales-filters`

1 credit per call

#### Parameters

Only the [common parameters](https://tokconnect.com/docs/api/reference-lists/#common-parameters).

#### Use it in Claude or ChatGPT

[Connect the MCP server](https://tokconnect.com/docs/api/mcp/) (`https://mcp.tokconnect.com/mcp`) and your AI calls this as the `reference` tool with `method: sales_filters`. Same data, same credit. [MCP setup](https://tokconnect.com/docs/api/mcp/)

MCP tool call:

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

#### Request

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

```python
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"])
```

```javascript
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:

```json
{
  "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**

- `data`objectThe tool's result. Compact by default; pass `detail=full` for the complete record.
- `data.category`string
- `data.market`string
- `data.order`string
- `data.tools`object
- `data.tools.category_trends`string
- `data.tools.creator_top_selling`object
- `data.tools.creator_top_selling.filters`array
- `data.tools.creator_top_selling.filters[].argument`string
- `data.tools.creator_top_selling.filters[].meaning`string
- `data.tools.creator_top_selling.filters[].values`string
- `data.tools.creator_top_selling.sort`array
- `data.tools.live_top_selling`string
- `data.tools.product_top_selling`object
- `data.tools.product_top_selling.filters`array
- `data.tools.product_top_selling.filters[].argument`string
- `data.tools.product_top_selling.filters[].meaning`string
- `data.tools.product_top_selling.filters[].values`string
- `data.tools.product_top_selling.sort`array
- `data.tools.shop_top_selling`object
- `data.tools.shop_top_selling.filters`array
- `data.tools.shop_top_selling.filters[].argument`string
- `data.tools.shop_top_selling.filters[].meaning`string
- `data.tools.shop_top_selling.filters[].values`string
- `data.tools.shop_top_selling.sort`array
- `data.tools.video_top_selling`string
- `data.window`string
- `meta`object
- `meta.credits_charged`integer1 on success.
- `meta.credits_remaining`integerCredits left this period, when known.
- `meta.request_id`stringQuote it to support.
- `next_cursor`stringPresent when there is another page: pass it back as cursor.

#### Errors

- `400` invalid input
- `401` key missing or not valid
- `402` out of credits
- `403` paid plan required
- `404` not found
- `429` rate limit, wait Retry-After
- `502` upstream failed, retry
- `503` busy, retry

Failed calls are never charged. Every code is explained on [API errors](https://tokconnect.com/docs/api/errors/).

Source: https://tokconnect.com/docs/api/reference-lists/