Get SPS Metric Diagnosis

GET

/analytics/202606/shop_performances/metrics/{metric_code}/diagnosis

Returns diagnosis details for a single SPS metric, including benchmark thresholds, trends, calculation details, and distribution details. Shop Performance Score (SPS) reflects a shop’s performance across key operational and service metrics on TikTok Shop. By integrating the read-only SPS APIs, ISVs can retrieve a shop’s score, tier, benefits, and metric benchmarks, diagnose performance gaps, and drill down to the products, logistics providers, aftersales types, orders, or chats associated with specific issues. This enables ISVs to embed actionable performance insights into their solutions, helping merchants identify problem areas faster and take targeted actions to improve shop performance. Available only for US-region shops. Use case guide: Click here

Authorizations

• accessToken

Parameters

Path Parameters

metric_code

required

string

Metric code. Possible values: NRR, NBFR, SFCR, OTDR, AHT, and IM_DSAT.

Query Parameters

shop_cipher

required

string

Identifies the shop. Obtain it from the Get Authorized Shops API.

locale

string

BCP 47 locale code used to localize response text. If omitted, the default locale is resolved from the request context.

trend_duration_days

integer format: int64

Number of days to look back for metric trend data. The value must be from 1 to 90. Default: 30.

Responses

200

Success

Media typeapplication/json

object

code

Status code; 0 means success.

integer format: int64

message

Success or failure message.

string

request_id

Request log ID.

string

data

object

benchmarks

Benchmark thresholds for this metric.

object

excellent_threshold

Excellent tier threshold.

string

poor_threshold

Poor tier threshold.

string

calculation_rule

Calculation details used to derive this metric.

object

denominator_label

Denominator label.

string

denominator_value

Denominator value.

string

numerator_label

Numerator label.

string

numerator_value

Numerator value.

string

dimension

SPS dimension that the metric belongs to.

string

distribution_details

Additional distribution details for the metric.

Array<object>

object

count

Number of items in the distribution bucket.

integer format: int64

name

Distribution detail name.

string

percent

Percentage of items in the distribution bucket, from 0 to 100.

string

evaluate_duration_days

Number of days included in the metric evaluation period.

integer format: int64

end_evaluation_time

Metric evaluation period end time. Unix timestamp in seconds.

integer format: int64

start_evaluation_time

Metric evaluation period start time. Unix timestamp in seconds.

integer format: int64

metric_code

Stable metric code. Possible values: NRR, NBFR, SFCR, OTDR, AHT, and IM_DSAT.

string

score

Metric score, from 0 to 5.

string

status

Metric status. Possible values include EXCELLENT, GOOD, POOR, CRITICAL and NIL.

string

status_text

Metric status text. Values like Excellent, Good, Normal, Attention.

string

trend

Metric trend over the requested lookback range.

object

data_points

Metric trend data points.

Array<object>

object

record_date

Trend date in yyyyMMdd format.

string

value

Metric value on the trend date, using the same unit as value_unit.

string

value

Metric value. Ratios are represented as values from 0 to 1; percentages are represented as values from 0 to 100.

string

value_unit

Unit of the metric value. Possible values include PERCENT and HOURS.

string

analyses

Diagnostic insights for the selected metric.

Array<object>

object

summaries

Summarized causes affecting the selected metric.

Array<string>

details

Detailed explanations for the selected metric diagnosis.

Array<string>

Example^generated

{
  "code": 1,
  "message": "example",
  "request_id": "example",
  "data": {
    "benchmarks": {
      "excellent_threshold": "example",
      "poor_threshold": "example"
    },
    "calculation_rule": {
      "denominator_label": "example",
      "denominator_value": "example",
      "numerator_label": "example",
      "numerator_value": "example"
    },
    "dimension": "example",
    "distribution_details": [
      {
        "count": 1,
        "name": "example",
        "percent": "example"
      }
    ],
    "evaluate_duration_days": 1,
    "end_evaluation_time": 1,
    "start_evaluation_time": 1,
    "metric_code": "example",
    "score": "example",
    "status": "example",
    "status_text": "example",
    "trend": {
      "data_points": [
        {
          "record_date": "example",
          "value": "example"
        }
      ]
    },
    "value": "example",
    "value_unit": "example",
    "analyses": [
      {
        "summaries": [
          "example"
        ],
        "details": [
          "example"
        ]
      }
    ]
  }
}