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 |
|---|---|---|---|
category_ids | array | optional | Category ID list filter |
category_ids[] | string | required | Category ID list filter |
commission_rate | number | optional | Affiliate product commission rate, such as `0.15` |
creator_id | string | optional | Expert ID filtering |
currency | string | optional | Currency unit, such as `USD` |
dateRange | string | optional | Time range, such as `last7Day`, `last30Day` |
is_affiliate | string | optional | Whether it is an alliance product: `PUBLIC_PLAN` (yes) or `NON_AFFILIATE` (no) |
is_tts_product | integer | optional | Whether the product is fully managed: `1` (fully managed) or `0` (not fully managed) |
language | string | optional | Return language, for example `zh-CN`, `en-US` |
livestream_id | string | optional | Returns the products associated with the specified live broadcast |
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 |
region | string | optional | Region/market code, such as `US` |
revenue_range | string | optional | Transaction amount / GMV range, left closed and right open |
shop_id | string | optional | Store ID filter |
sortField | object | optional | Sorting specification object, the available fields are subject to those actually accepted by the gateway. |
unit_price_range | string | optional | Product price range, left closed and right open |
video_id | string | optional | Returns the products associated with the specified video |
Response example
Platform response envelope. code 0 indicates success or acceptance; data contains the business result.
No response example is published for this API. Refer to the response fields below.
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 | Default HTTP response for both success and many business errors. Only outer JSON code 0 indicates success or asynchronous acceptance; inspect data for the result. |
| 429 | Execution admission rate limit; honor Retry-After when present. |
| 503 | Execution admission is temporarily unavailable; honor Retry-After when present. |
| Opt-in | X-Nexscope-Http-Status: semantic maps controller-handled business errors to HTTP status on run and task routes. Pre-authentication failures, such as a missing or invalid API key (code 11209, including an incomplete or corrupted copy) or an expired website login session (code 12001), may still return HTTP 200 before this mapping. Always check the outer JSON code; malformed requests and infrastructure failures may also return non-200 HTTP responses. |
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.