POST
https://api.nexscope.ai/kd/product/rankRun this API
Send a JSON request to execute this API and receive the documented response payload.
Endpoint
| Method | POST |
| Path | https://api.nexscope.ai/kd/product/rank |
| Auth | Bearer API key |
| Content-Type | application/json |
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
region | string | optional | Region/market code, such as `US` |
dateRange | string | optional | Time range, such as `last7Day`, `last30Day` |
currency | string | optional | Currency unit, such as `USD` |
language | string | optional | Return language, for example `zh-CN`, `en-US` |
category_ids | string[] | optional | Category ID list filter |
shop_id | string | optional | Store ID filter |
creator_id | string | optional | Expert ID filtering |
video_id | string | optional | Returns the products associated with the specified video |
livestream_id | string | optional | Returns the products associated with the specified live broadcast |
revenue_range | string | optional | Transaction amount / GMV range, left closed and right open |
is_affiliate | string | optional | Whether it is an alliance product: `PUBLIC_PLAN` (yes) or `NON_AFFILIATE` (no) |
commission_rate | number | optional | Affiliate product commission rate, such as `0.15` |
is_tts_product | integer | optional | Whether the product is fully managed: `1` (fully managed) or `0` (not fully managed) |
unit_price_range | string | optional | Product price range, left closed and right open |
sortField | object | optional | Sorting specification object, the available fields are subject to those actually accepted by the gateway. |
pageNumber | integer | optional | Page number, range 1-5 |
pageSize | integer | optional | Number of items per page, range 5-100 |
productId | string | required | TikTok product ID, such as `1729508370969629931`; the string can avoid the loss of large integer precision and can be obtained from the `product_id` of the list response |
Code example
{
"currency": "USD",
"dateRange": "last7Day",
"pageNumber": 1,
"pageSize": 20,
"region": "US"
}Response example
Platform response envelope. code 0 indicates success or acceptance; data contains the business result.
{
"code": 0,
"cost": "-1",
"data": {},
"msg": null,
"time": "2026-01-01 00:00:00",
"traceId": null,
"ts": "0"
}Response fields
Response field reference (37 fields)
| Name | Type | Required | Description |
|---|---|---|---|
errcode | integer | optional | Business status code, `200` indicates success |
data | array | optional | List or detailed data; real response does not return `total` |
costToken | integer | optional | The deduction token for this call is usually `14000` |
errmsg | string | optional | Status message, `ok` on success |
product_id | string | optional | Product ID (string format to avoid loss of large integer precision), can be used as `productId` to query details |
product_name | string | optional | Product title |
unit_price | number | optional | Unit price, currency depends on `region`, such as US is USD |
sales_volumn | integer | optional | Sales volume (units); field name `sales_volumn`, not `volume` |
revenue | number | optional | Total sales / GMV, equals `video_revenue` + `live_revenue` + `showcase_revenue` |
video_revenue | number | optional | Video channel sales |
live_revenue | number | optional | Live broadcast channel sales |
showcase_revenue | number | optional | Window/display channel sales |
revenue_growth_rate | number | optional | Sales growth rate (percentage, e.g. `27.94` represents 27.94%) |
commission_rate | number | optional | Commission rate, direct percentage, such as `25.0` means 25%, not basis points |
launch_date | string | optional | Date on shelves (`YYYY-MM-DD`) |
product_id | string | optional | Unique product ID (string, to avoid loss of large integer precision) |
product_name | string | optional | Product name |
product_region | string | optional | The region/market where the product is located, such as `us` |
product_shop_id | string | optional | Store ID |
pri_cate_id | string | optional | First level category ID |
sec_cate_id | string | optional | Secondary category ID |
ter_cate_id | string | optional | Third-level category ID |
unit_price | number | optional | Unit price in requested `currency` currency |
min_price | number | optional | Lowest price in requested `currency` currency |
max_price | number | optional | Highest price in requested `currency` currency |
revenue | number | optional | Total sales/GMV by requested `currency` currency |
sales_volumn | integer | optional | Sales volume, field spelled `volumn` |
commission_rate | number | optional | Commission rate, direct percentage, `25.0` means 25% |
product_review_count | integer | optional | Number of product reviews |
launch_date | string | optional | Date on shelves (`YYYY-MM-DD`) |
delivery_type | string | optional | Shipping method, such as `local` |
video_number | integer | optional | Number of associated videos |
video_revenue | number | optional | Sales generated by video in requested `currency` currency |
live_number | integer | optional | Number of associated live broadcasts |
live_revenue | number | optional | Sales generated by live streaming, in requested `currency` currency |
shopping_mall_revenue | number | optional | Marketplace sales in requested `currency` currency |
creator_number | integer | optional | Number of connected people |
Responses
| Code | Description |
|---|---|
| 200 | HTTP request completed. Check JSON code; only 0 indicates business success or acceptance. |
| 400 | Request JSON or required API parameters are invalid. |
| 401 | API key is missing, invalid, or cannot be matched to a user. |
| 5xx | API execution or upstream service failed. |
Data source, freshness, and limitations
Source, freshness, coverage, rate limits, and estimation notes are not specified in this API definition unless they appear in the request or response field documentation above. Do not assume official marketplace data or real-time freshness when it is not explicitly documented.