# Tmall Monthly Product Sales

Tmall monthly sales with live, BYBT, and B/C shop details.

ID: dataset:tmall · Region: global · Status: available

catalog_version: 938eb1e3bdb6476050bf2983e6e8db1edcf9f0942d16c7ebd2029dcd28295afe
updated_at: 2026-10-21T10:40:52.196893+00:00

Tmall only

Dataset releases define historical periods; live reads describe request-time data and do not guarantee completeness.

Docs: https://docs.kleardata.ai/capabilities/dataset%3Atmall

## GET /v1/datasets/tmall

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "tmall"
    },
    "task": {
      "pattern": "^[a-z][a-z0-9_]*$",
      "type": "string"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall"
}
```

### Synthetic response / 合成响应

```json
{
  "dimensions": [
    {
      "desc": "天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。",
      "desc_i18n": {
        "en": "Stable Tmall product identifier used for exact filtering and paired with product_url.",
        "zh-CN": "天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_id",
      "reference_formats": [
        "tmall_product_id",
        "tmall_product_url"
      ],
      "type": "string"
    },
    {
      "desc": "该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。",
      "desc_i18n": {
        "en": "Product title recorded for the month; it is returned for display and grouping, but it is not a direct query_metrics or query_details filter. Use search_products for title lookup.",
        "zh-CN": "该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "title",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "根据 product_id 生成的标准天猫商品详情页链接。",
      "desc_i18n": {
        "en": "Canonical Tmall product-detail URL generated from product_id.",
        "zh-CN": "根据 product_id 生成的标准天猫商品详情页链接。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_url",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。",
      "desc_i18n": {
        "en": "Stable Tmall shop identifier used for exact filtering and paired with shop_url.",
        "zh-CN": "天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_id",
      "reference_formats": [
        "tmall_shop_id",
        "tmall_shop_url"
      ],
      "type": "string"
    },
    {
      "desc": "根据 shop_id 生成的标准天猫店铺页面链接。",
      "desc_i18n": {
        "en": "Canonical Tmall shop-page URL generated from shop_id.",
        "zh-CN": "根据 shop_id 生成的标准天猫店铺页面链接。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_url",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。",
      "desc_i18n": {
        "en": "Brand name recorded by the upstream Tmall data, paired with brand_id; it may be missing or vary in spelling.",
        "zh-CN": "天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。"
      },
      "dictionary_searchable": true,
      "name": "brand",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。",
      "desc_i18n": {
        "en": "Level-1 category name in the upstream Tmall hierarchy, paired with category_l1_id.",
        "zh-CN": "天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。"
      },
      "dictionary_searchable": true,
      "name": "category_l1",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。",
      "desc_i18n": {
        "en": "Level-2 category name in the upstream Tmall hierarchy, paired with category_l2_id.",
        "zh-CN": "天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。"
      },
      "dictionary_searchable": true,
      "name": "category_l2",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。",
      "desc_i18n": {
        "en": "Level-3 category name in the upstream Tmall hierarchy, paired with category_l3_id.",
        "zh-CN": "天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。"
      },
      "dictionary_searchable": true,
      "name": "category_l3",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。",
      "desc_i18n": {
        "en": "Shop name recorded by Tmall, paired with shop_id; it may change over time.",
        "zh-CN": "天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。"
      },
      "dictionary_searchable": true,
      "name": "shop",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。",
      "desc_i18n": {
        "en": "Calendar month to which the product sales record belongs, formatted as YYYY-MM; the dataset grain is monthly.",
        "zh-CN": "商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。"
      },
      "dictionary_searchable": false,
      "name": "month",
      "reference_formats": [],
      "type": "time"
    },
    {
      "desc": "商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。",
      "desc_i18n": {
        "en": "Whether the product has appeared in live commerce during the record month; null or empty means unknown, not no.",
        "zh-CN": "商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。"
      },
      "dictionary_searchable": false,
      "name": "is_live",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "is_unknown",
          "is_known"
        ],
        "groupable": true,
        "searchable": false
      },
      "reference_formats": [],
      "type": "string",
      "unknown_value_policy": "null_or_empty_is_unknown_not_no",
      "value_label_i18n": {
        "en": "whether the product has appeared in live commerce",
        "zh-CN": "是否上过直播"
      }
    },
    {
      "desc": "商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。",
      "desc_i18n": {
        "en": "Whether the product participates in the RMB 10B subsidy program during the record month; null or empty means unknown, not no.",
        "zh-CN": "商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。"
      },
      "dictionary_searchable": false,
      "name": "has_bybt",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "is_unknown",
          "is_known"
        ],
        "groupable": true,
        "searchable": false
      },
      "reference_formats": [],
      "type": "string",
      "unknown_value_policy": "null_or_empty_is_unknown_not_no",
      "value_label_i18n": {
        "en": "whether the product participates in the RMB 10B subsidy program",
        "zh-CN": "是否参加百亿补贴"
      }
    },
    {
      "desc": "天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。",
      "desc_i18n": {
        "en": "Tmall B/C shop type after trimming blank values; null means the type is unknown.",
        "zh-CN": "天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。"
      },
      "dictionary_searchable": true,
      "name": "bc_type",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "is_unknown",
          "is_known"
        ],
        "groupable": true,
        "searchable": true
      },
      "reference_formats": [],
      "type": "string",
      "unknown_value_policy": "null_or_empty_is_unknown_not_no",
      "value_label_i18n": {
        "en": "B/C shop type",
        "zh-CN": "B/C 店铺标识"
      }
    }
  ],
  "metrics": [
    {
      "certified": true,
      "desc": "券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。",
      "desc_i18n": {
        "en": "Post-coupon sales amount in CNY; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.",
        "zh-CN": "券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。"
      },
      "name": "gmv"
    },
    {
      "certified": false,
      "desc": "商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。",
      "desc_i18n": {
        "en": "Units sold; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.",
        "zh-CN": "商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。"
      },
      "name": "units"
    },
    {
      "certified": false,
      "desc": "加权平均成交价，单位为人民币元，按 SUM(gmv) / SUM(units) 计算；总销量为 0 时返回空，仅支持聚合查询。",
      "desc_i18n": {
        "en": "Weighted average selling price in CNY, calculated as SUM(gmv) / SUM(units); null when total units is zero, and available only in aggregate queries.",
        "zh-CN": "加权平均成交价，单位为人民币元，按 SUM(gmv) / SUM(units) 计算；总销量为 0 时返回空，仅支持聚合查询。"
      },
      "name": "asp"
    }
  ]
}
```

- dimensions (array<object>): No field description available
- metrics (array<object>): No field description available
## describe

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "tmall"
    },
    "task": {
      "pattern": "^[a-z][a-z0-9_]*$",
      "type": "string"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall"
}
```

### Synthetic response / 合成响应

```json
{
  "dimensions": [
    {
      "desc": "天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。",
      "desc_i18n": {
        "en": "Stable Tmall product identifier used for exact filtering and paired with product_url.",
        "zh-CN": "天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_id",
      "reference_formats": [
        "tmall_product_id",
        "tmall_product_url"
      ],
      "type": "string"
    },
    {
      "desc": "该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。",
      "desc_i18n": {
        "en": "Product title recorded for the month; it is returned for display and grouping, but it is not a direct query_metrics or query_details filter. Use search_products for title lookup.",
        "zh-CN": "该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "title",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "根据 product_id 生成的标准天猫商品详情页链接。",
      "desc_i18n": {
        "en": "Canonical Tmall product-detail URL generated from product_id.",
        "zh-CN": "根据 product_id 生成的标准天猫商品详情页链接。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_url",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。",
      "desc_i18n": {
        "en": "Stable Tmall shop identifier used for exact filtering and paired with shop_url.",
        "zh-CN": "天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_id",
      "reference_formats": [
        "tmall_shop_id",
        "tmall_shop_url"
      ],
      "type": "string"
    },
    {
      "desc": "根据 shop_id 生成的标准天猫店铺页面链接。",
      "desc_i18n": {
        "en": "Canonical Tmall shop-page URL generated from shop_id.",
        "zh-CN": "根据 shop_id 生成的标准天猫店铺页面链接。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_url",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。",
      "desc_i18n": {
        "en": "Brand name recorded by the upstream Tmall data, paired with brand_id; it may be missing or vary in spelling.",
        "zh-CN": "天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。"
      },
      "dictionary_searchable": true,
      "name": "brand",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。",
      "desc_i18n": {
        "en": "Level-1 category name in the upstream Tmall hierarchy, paired with category_l1_id.",
        "zh-CN": "天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。"
      },
      "dictionary_searchable": true,
      "name": "category_l1",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。",
      "desc_i18n": {
        "en": "Level-2 category name in the upstream Tmall hierarchy, paired with category_l2_id.",
        "zh-CN": "天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。"
      },
      "dictionary_searchable": true,
      "name": "category_l2",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。",
      "desc_i18n": {
        "en": "Level-3 category name in the upstream Tmall hierarchy, paired with category_l3_id.",
        "zh-CN": "天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。"
      },
      "dictionary_searchable": true,
      "name": "category_l3",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。",
      "desc_i18n": {
        "en": "Shop name recorded by Tmall, paired with shop_id; it may change over time.",
        "zh-CN": "天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。"
      },
      "dictionary_searchable": true,
      "name": "shop",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。",
      "desc_i18n": {
        "en": "Calendar month to which the product sales record belongs, formatted as YYYY-MM; the dataset grain is monthly.",
        "zh-CN": "商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。"
      },
      "dictionary_searchable": false,
      "name": "month",
      "reference_formats": [],
      "type": "time"
    },
    {
      "desc": "商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。",
      "desc_i18n": {
        "en": "Whether the product has appeared in live commerce during the record month; null or empty means unknown, not no.",
        "zh-CN": "商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。"
      },
      "dictionary_searchable": false,
      "name": "is_live",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "is_unknown",
          "is_known"
        ],
        "groupable": true,
        "searchable": false
      },
      "reference_formats": [],
      "type": "string",
      "unknown_value_policy": "null_or_empty_is_unknown_not_no",
      "value_label_i18n": {
        "en": "whether the product has appeared in live commerce",
        "zh-CN": "是否上过直播"
      }
    },
    {
      "desc": "商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。",
      "desc_i18n": {
        "en": "Whether the product participates in the RMB 10B subsidy program during the record month; null or empty means unknown, not no.",
        "zh-CN": "商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。"
      },
      "dictionary_searchable": false,
      "name": "has_bybt",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "is_unknown",
          "is_known"
        ],
        "groupable": true,
        "searchable": false
      },
      "reference_formats": [],
      "type": "string",
      "unknown_value_policy": "null_or_empty_is_unknown_not_no",
      "value_label_i18n": {
        "en": "whether the product participates in the RMB 10B subsidy program",
        "zh-CN": "是否参加百亿补贴"
      }
    },
    {
      "desc": "天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。",
      "desc_i18n": {
        "en": "Tmall B/C shop type after trimming blank values; null means the type is unknown.",
        "zh-CN": "天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。"
      },
      "dictionary_searchable": true,
      "name": "bc_type",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "is_unknown",
          "is_known"
        ],
        "groupable": true,
        "searchable": true
      },
      "reference_formats": [],
      "type": "string",
      "unknown_value_policy": "null_or_empty_is_unknown_not_no",
      "value_label_i18n": {
        "en": "B/C shop type",
        "zh-CN": "B/C 店铺标识"
      }
    }
  ],
  "metrics": [
    {
      "certified": true,
      "desc": "券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。",
      "desc_i18n": {
        "en": "Post-coupon sales amount in CNY; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.",
        "zh-CN": "券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。"
      },
      "name": "gmv"
    },
    {
      "certified": false,
      "desc": "商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。",
      "desc_i18n": {
        "en": "Units sold; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.",
        "zh-CN": "商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。"
      },
      "name": "units"
    },
    {
      "certified": false,
      "desc": "加权平均成交价，单位为人民币元，按 SUM(gmv) / SUM(units) 计算；总销量为 0 时返回空，仅支持聚合查询。",
      "desc_i18n": {
        "en": "Weighted average selling price in CNY, calculated as SUM(gmv) / SUM(units); null when total units is zero, and available only in aggregate queries.",
        "zh-CN": "加权平均成交价，单位为人民币元，按 SUM(gmv) / SUM(units) 计算；总销量为 0 时返回空，仅支持聚合查询。"
      },
      "name": "asp"
    }
  ]
}
```

- dimensions (array<object>): No field description available
- metrics (array<object>): No field description available
## asklear describe

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "tmall"
    },
    "task": {
      "pattern": "^[a-z][a-z0-9_]*$",
      "type": "string"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall"
}
```

### Synthetic response / 合成响应

```json
{
  "dimensions": [
    {
      "desc": "天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。",
      "desc_i18n": {
        "en": "Stable Tmall product identifier used for exact filtering and paired with product_url.",
        "zh-CN": "天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_id",
      "reference_formats": [
        "tmall_product_id",
        "tmall_product_url"
      ],
      "type": "string"
    },
    {
      "desc": "该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。",
      "desc_i18n": {
        "en": "Product title recorded for the month; it is returned for display and grouping, but it is not a direct query_metrics or query_details filter. Use search_products for title lookup.",
        "zh-CN": "该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "title",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "根据 product_id 生成的标准天猫商品详情页链接。",
      "desc_i18n": {
        "en": "Canonical Tmall product-detail URL generated from product_id.",
        "zh-CN": "根据 product_id 生成的标准天猫商品详情页链接。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_url",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。",
      "desc_i18n": {
        "en": "Stable Tmall shop identifier used for exact filtering and paired with shop_url.",
        "zh-CN": "天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_id",
      "reference_formats": [
        "tmall_shop_id",
        "tmall_shop_url"
      ],
      "type": "string"
    },
    {
      "desc": "根据 shop_id 生成的标准天猫店铺页面链接。",
      "desc_i18n": {
        "en": "Canonical Tmall shop-page URL generated from shop_id.",
        "zh-CN": "根据 shop_id 生成的标准天猫店铺页面链接。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_url",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。",
      "desc_i18n": {
        "en": "Brand name recorded by the upstream Tmall data, paired with brand_id; it may be missing or vary in spelling.",
        "zh-CN": "天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。"
      },
      "dictionary_searchable": true,
      "name": "brand",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。",
      "desc_i18n": {
        "en": "Level-1 category name in the upstream Tmall hierarchy, paired with category_l1_id.",
        "zh-CN": "天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。"
      },
      "dictionary_searchable": true,
      "name": "category_l1",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。",
      "desc_i18n": {
        "en": "Level-2 category name in the upstream Tmall hierarchy, paired with category_l2_id.",
        "zh-CN": "天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。"
      },
      "dictionary_searchable": true,
      "name": "category_l2",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。",
      "desc_i18n": {
        "en": "Level-3 category name in the upstream Tmall hierarchy, paired with category_l3_id.",
        "zh-CN": "天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。"
      },
      "dictionary_searchable": true,
      "name": "category_l3",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。",
      "desc_i18n": {
        "en": "Shop name recorded by Tmall, paired with shop_id; it may change over time.",
        "zh-CN": "天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。"
      },
      "dictionary_searchable": true,
      "name": "shop",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。",
      "desc_i18n": {
        "en": "Calendar month to which the product sales record belongs, formatted as YYYY-MM; the dataset grain is monthly.",
        "zh-CN": "商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。"
      },
      "dictionary_searchable": false,
      "name": "month",
      "reference_formats": [],
      "type": "time"
    },
    {
      "desc": "商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。",
      "desc_i18n": {
        "en": "Whether the product has appeared in live commerce during the record month; null or empty means unknown, not no.",
        "zh-CN": "商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。"
      },
      "dictionary_searchable": false,
      "name": "is_live",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "is_unknown",
          "is_known"
        ],
        "groupable": true,
        "searchable": false
      },
      "reference_formats": [],
      "type": "string",
      "unknown_value_policy": "null_or_empty_is_unknown_not_no",
      "value_label_i18n": {
        "en": "whether the product has appeared in live commerce",
        "zh-CN": "是否上过直播"
      }
    },
    {
      "desc": "商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。",
      "desc_i18n": {
        "en": "Whether the product participates in the RMB 10B subsidy program during the record month; null or empty means unknown, not no.",
        "zh-CN": "商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。"
      },
      "dictionary_searchable": false,
      "name": "has_bybt",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "is_unknown",
          "is_known"
        ],
        "groupable": true,
        "searchable": false
      },
      "reference_formats": [],
      "type": "string",
      "unknown_value_policy": "null_or_empty_is_unknown_not_no",
      "value_label_i18n": {
        "en": "whether the product participates in the RMB 10B subsidy program",
        "zh-CN": "是否参加百亿补贴"
      }
    },
    {
      "desc": "天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。",
      "desc_i18n": {
        "en": "Tmall B/C shop type after trimming blank values; null means the type is unknown.",
        "zh-CN": "天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。"
      },
      "dictionary_searchable": true,
      "name": "bc_type",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "is_unknown",
          "is_known"
        ],
        "groupable": true,
        "searchable": true
      },
      "reference_formats": [],
      "type": "string",
      "unknown_value_policy": "null_or_empty_is_unknown_not_no",
      "value_label_i18n": {
        "en": "B/C shop type",
        "zh-CN": "B/C 店铺标识"
      }
    }
  ],
  "metrics": [
    {
      "certified": true,
      "desc": "券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。",
      "desc_i18n": {
        "en": "Post-coupon sales amount in CNY; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.",
        "zh-CN": "券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。"
      },
      "name": "gmv"
    },
    {
      "certified": false,
      "desc": "商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。",
      "desc_i18n": {
        "en": "Units sold; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.",
        "zh-CN": "商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。"
      },
      "name": "units"
    },
    {
      "certified": false,
      "desc": "加权平均成交价，单位为人民币元，按 SUM(gmv) / SUM(units) 计算；总销量为 0 时返回空，仅支持聚合查询。",
      "desc_i18n": {
        "en": "Weighted average selling price in CNY, calculated as SUM(gmv) / SUM(units); null when total units is zero, and available only in aggregate queries.",
        "zh-CN": "加权平均成交价，单位为人民币元，按 SUM(gmv) / SUM(units) 计算；总销量为 0 时返回空，仅支持聚合查询。"
      },
      "name": "asp"
    }
  ]
}
```

- dimensions (array<object>): No field description available
- metrics (array<object>): No field description available
## GET /v1/datasets/tmall/sample

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Example row shape only; samples are not analytical evidence.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "tmall"
    },
    "n": {
      "maximum": 10,
      "minimum": 1,
      "type": "integer"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "dataset"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "n": 10
}
```

### Synthetic response / 合成响应

```json
{
  "data": []
}
```

- data (array<object>): No field description available
## sample_rows

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Example row shape only; samples are not analytical evidence.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "tmall"
    },
    "n": {
      "maximum": 10,
      "minimum": 1,
      "type": "integer"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "dataset"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "n": 10
}
```

### Synthetic response / 合成响应

```json
{
  "data": []
}
```

- data (array<object>): No field description available
## asklear sample

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Example row shape only; samples are not analytical evidence.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "tmall"
    },
    "n": {
      "maximum": 10,
      "minimum": 1,
      "type": "integer"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "dataset"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "n": 10
}
```

### Synthetic response / 合成响应

```json
{
  "data": []
}
```

- data (array<object>): No field description available
## POST /v1/query_metrics

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing dataset query pricing and account authorization apply.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "filters": {
          "description": "Query-specific filters; shared scope belongs in common_filters.",
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        "group_by": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "limit": {
          "default": 100,
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "metrics": {
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        "order_by": {
          "items": {
            "$ref": "#/$defs/Schema2"
          },
          "type": "array"
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema4"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Omit to inherit the main query time; provide for cross-period analysis."
        }
      },
      "required": [
        "name",
        "metrics"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "dir": {
          "default": "asc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "field": {
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "Schema3": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema4": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "additional_queries": {
      "description": "Up to three additional analyses for shares, comparisons, or multiple views.",
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "common_filters": {
      "description": "Filters applied to every query in the bundle.",
      "items": {
        "$ref": "#/$defs/Schema3"
      },
      "type": "array"
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "default": false,
      "description": "Set true only when the user asks for a price preview.",
      "type": "boolean"
    },
    "filters": {
      "description": "Aligned query scope. Resolve user-supplied brand, shop, and category names with search_values; product/shop URLs are values for product_id/shop_id.",
      "items": {
        "$ref": "#/$defs/Schema3"
      },
      "type": "array"
    },
    "group_by": {
      "description": "Exact public result dimensions. Include month for a monthly trend; for entity results include the declared ID, name, and URL fields.",
      "items": {
        "enum": [
          "product_id",
          "title",
          "product_url",
          "shop_id",
          "shop_url",
          "brand",
          "category_l1",
          "category_l2",
          "category_l3",
          "shop",
          "month",
          "is_live",
          "has_bybt",
          "bc_type"
        ]
      },
      "type": "array"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "MCP paid non-dry-run single operations require idempotency_key; REST and free previews may omit it. Bundles reject idempotency_key; omit it with additional_queries. Bundles are non-atomic; recover failed items as independent single operations, not whole-bundle replay."
    },
    "limit": {
      "default": 100,
      "maximum": 1000,
      "minimum": 1,
      "type": "integer"
    },
    "main_query_name": {
      "anyOf": [
        {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Main result ID for a bundle; omit for one query. Use lowercase ASCII, digits, and underscores."
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "metrics": {
      "description": "Public metrics requested by the user; do not add unrequested metrics.",
      "items": {
        "enum": [
          "gmv",
          "units",
          "asp"
        ]
      },
      "minItems": 1,
      "type": "array"
    },
    "order_by": {
      "description": "Sort by a returned metric or groupable dimension.",
      "items": {
        "$ref": "#/$defs/Schema2"
      },
      "type": "array"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    },
    "time": {
      "$ref": "#/$defs/Schema4",
      "description": "Absolute range or last_complete_months; relative time needs no describe."
    }
  },
  "required": [
    "dataset",
    "metrics",
    "time"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "group_by": [
    "brand"
  ],
  "limit": 10,
  "metrics": [
    "gmv"
  ],
  "order_by": [
    {
      "dir": "desc",
      "field": "gmv"
    }
  ],
  "task_query": "查看天猫最近一个完整月的品牌销售额排名",
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

```json
{
  "data": [],
  "meta": {
    "dataset": "tmall"
  }
}
```

- data[].product_id (string): Stable Tmall product identifier used for exact filtering and paired with product_url.
- data[].title (string): Product title recorded for the month; it is returned for display and grouping, but it is not a direct query_metrics or query_details filter. Use search_products for title lookup.
- data[].product_url (string): Canonical Tmall product-detail URL generated from product_id.
- data[].shop_id (string): Stable Tmall shop identifier used for exact filtering and paired with shop_url.
- data[].shop_url (string): Canonical Tmall shop-page URL generated from shop_id.
- data[].brand (string): Brand name recorded by the upstream Tmall data, paired with brand_id; it may be missing or vary in spelling.
- data[].category_l1 (string): Level-1 category name in the upstream Tmall hierarchy, paired with category_l1_id.
- data[].category_l2 (string): Level-2 category name in the upstream Tmall hierarchy, paired with category_l2_id.
- data[].category_l3 (string): Level-3 category name in the upstream Tmall hierarchy, paired with category_l3_id.
- data[].shop (string): Shop name recorded by Tmall, paired with shop_id; it may change over time.
- data[].month (time): Calendar month to which the product sales record belongs, formatted as YYYY-MM; the dataset grain is monthly.
- data[].is_live (string): Whether the product has appeared in live commerce during the record month; null or empty means unknown, not no.
- data[].has_bybt (string): Whether the product participates in the RMB 10B subsidy program during the record month; null or empty means unknown, not no.
- data[].bc_type (string): Tmall B/C shop type after trimming blank values; null means the type is unknown.
- data[].gmv (number): Post-coupon sales amount in CNY; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
- data[].units (number): Units sold; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
- data[].asp (number): Weighted average selling price in CNY, calculated as SUM(gmv) / SUM(units); null when total units is zero, and available only in aggregate queries.
## query_metrics

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing dataset query pricing and account authorization apply.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "filters": {
          "description": "Query-specific filters; shared scope belongs in common_filters.",
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        "group_by": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "limit": {
          "default": 100,
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "metrics": {
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        "order_by": {
          "items": {
            "$ref": "#/$defs/Schema2"
          },
          "type": "array"
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema4"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Omit to inherit the main query time; provide for cross-period analysis."
        }
      },
      "required": [
        "name",
        "metrics"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "dir": {
          "default": "asc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "field": {
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "Schema3": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema4": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "additional_queries": {
      "description": "Up to three additional analyses for shares, comparisons, or multiple views.",
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "common_filters": {
      "description": "Filters applied to every query in the bundle.",
      "items": {
        "$ref": "#/$defs/Schema3"
      },
      "type": "array"
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "default": false,
      "description": "Set true only when the user asks for a price preview.",
      "type": "boolean"
    },
    "filters": {
      "description": "Aligned query scope. Resolve user-supplied brand, shop, and category names with search_values; product/shop URLs are values for product_id/shop_id.",
      "items": {
        "$ref": "#/$defs/Schema3"
      },
      "type": "array"
    },
    "group_by": {
      "description": "Exact public result dimensions. Include month for a monthly trend; for entity results include the declared ID, name, and URL fields.",
      "items": {
        "enum": [
          "product_id",
          "title",
          "product_url",
          "shop_id",
          "shop_url",
          "brand",
          "category_l1",
          "category_l2",
          "category_l3",
          "shop",
          "month",
          "is_live",
          "has_bybt",
          "bc_type"
        ]
      },
      "type": "array"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "MCP paid non-dry-run single operations require idempotency_key; REST and free previews may omit it. Bundles reject idempotency_key; omit it with additional_queries. Bundles are non-atomic; recover failed items as independent single operations, not whole-bundle replay."
    },
    "limit": {
      "default": 100,
      "maximum": 1000,
      "minimum": 1,
      "type": "integer"
    },
    "main_query_name": {
      "anyOf": [
        {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Main result ID for a bundle; omit for one query. Use lowercase ASCII, digits, and underscores."
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "metrics": {
      "description": "Public metrics requested by the user; do not add unrequested metrics.",
      "items": {
        "enum": [
          "gmv",
          "units",
          "asp"
        ]
      },
      "minItems": 1,
      "type": "array"
    },
    "order_by": {
      "description": "Sort by a returned metric or groupable dimension.",
      "items": {
        "$ref": "#/$defs/Schema2"
      },
      "type": "array"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    },
    "time": {
      "$ref": "#/$defs/Schema4",
      "description": "Absolute range or last_complete_months; relative time needs no describe."
    }
  },
  "required": [
    "dataset",
    "metrics",
    "time"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "group_by": [
    "brand"
  ],
  "idempotency_key": "directory-example",
  "limit": 10,
  "metrics": [
    "gmv"
  ],
  "order_by": [
    {
      "dir": "desc",
      "field": "gmv"
    }
  ],
  "task_query": "查看天猫最近一个完整月的品牌销售额排名",
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

```json
{
  "data": [],
  "meta": {
    "dataset": "tmall"
  }
}
```

- data[].product_id (string): Stable Tmall product identifier used for exact filtering and paired with product_url.
- data[].title (string): Product title recorded for the month; it is returned for display and grouping, but it is not a direct query_metrics or query_details filter. Use search_products for title lookup.
- data[].product_url (string): Canonical Tmall product-detail URL generated from product_id.
- data[].shop_id (string): Stable Tmall shop identifier used for exact filtering and paired with shop_url.
- data[].shop_url (string): Canonical Tmall shop-page URL generated from shop_id.
- data[].brand (string): Brand name recorded by the upstream Tmall data, paired with brand_id; it may be missing or vary in spelling.
- data[].category_l1 (string): Level-1 category name in the upstream Tmall hierarchy, paired with category_l1_id.
- data[].category_l2 (string): Level-2 category name in the upstream Tmall hierarchy, paired with category_l2_id.
- data[].category_l3 (string): Level-3 category name in the upstream Tmall hierarchy, paired with category_l3_id.
- data[].shop (string): Shop name recorded by Tmall, paired with shop_id; it may change over time.
- data[].month (time): Calendar month to which the product sales record belongs, formatted as YYYY-MM; the dataset grain is monthly.
- data[].is_live (string): Whether the product has appeared in live commerce during the record month; null or empty means unknown, not no.
- data[].has_bybt (string): Whether the product participates in the RMB 10B subsidy program during the record month; null or empty means unknown, not no.
- data[].bc_type (string): Tmall B/C shop type after trimming blank values; null means the type is unknown.
- data[].gmv (number): Post-coupon sales amount in CNY; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
- data[].units (number): Units sold; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
- data[].asp (number): Weighted average selling price in CNY, calculated as SUM(gmv) / SUM(units); null when total units is zero, and available only in aggregate queries.
## asklear query

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing dataset query pricing and account authorization apply.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "filters": {
          "description": "Query-specific filters; shared scope belongs in common_filters.",
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        "group_by": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "limit": {
          "default": 100,
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "metrics": {
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        "order_by": {
          "items": {
            "$ref": "#/$defs/Schema2"
          },
          "type": "array"
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema4"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Omit to inherit the main query time; provide for cross-period analysis."
        }
      },
      "required": [
        "name",
        "metrics"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "dir": {
          "default": "asc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "field": {
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "Schema3": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema4": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "additional_queries": {
      "description": "Up to three additional analyses for shares, comparisons, or multiple views.",
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "common_filters": {
      "description": "Filters applied to every query in the bundle.",
      "items": {
        "$ref": "#/$defs/Schema3"
      },
      "type": "array"
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "default": false,
      "description": "Set true only when the user asks for a price preview.",
      "type": "boolean"
    },
    "filters": {
      "description": "Aligned query scope. Resolve user-supplied brand, shop, and category names with search_values; product/shop URLs are values for product_id/shop_id.",
      "items": {
        "$ref": "#/$defs/Schema3"
      },
      "type": "array"
    },
    "group_by": {
      "description": "Exact public result dimensions. Include month for a monthly trend; for entity results include the declared ID, name, and URL fields.",
      "items": {
        "enum": [
          "product_id",
          "title",
          "product_url",
          "shop_id",
          "shop_url",
          "brand",
          "category_l1",
          "category_l2",
          "category_l3",
          "shop",
          "month",
          "is_live",
          "has_bybt",
          "bc_type"
        ]
      },
      "type": "array"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "MCP paid non-dry-run single operations require idempotency_key; REST and free previews may omit it. Bundles reject idempotency_key; omit it with additional_queries. Bundles are non-atomic; recover failed items as independent single operations, not whole-bundle replay."
    },
    "limit": {
      "default": 100,
      "maximum": 1000,
      "minimum": 1,
      "type": "integer"
    },
    "main_query_name": {
      "anyOf": [
        {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Main result ID for a bundle; omit for one query. Use lowercase ASCII, digits, and underscores."
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "metrics": {
      "description": "Public metrics requested by the user; do not add unrequested metrics.",
      "items": {
        "enum": [
          "gmv",
          "units",
          "asp"
        ]
      },
      "minItems": 1,
      "type": "array"
    },
    "order_by": {
      "description": "Sort by a returned metric or groupable dimension.",
      "items": {
        "$ref": "#/$defs/Schema2"
      },
      "type": "array"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    },
    "time": {
      "$ref": "#/$defs/Schema4",
      "description": "Absolute range or last_complete_months; relative time needs no describe."
    }
  },
  "required": [
    "dataset",
    "metrics",
    "time"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "group_by": [
    "brand"
  ],
  "idempotency_key": "directory-example",
  "limit": 10,
  "metrics": [
    "gmv"
  ],
  "order_by": [
    {
      "dir": "desc",
      "field": "gmv"
    }
  ],
  "task_query": "查看天猫最近一个完整月的品牌销售额排名",
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

```json
{
  "data": [],
  "meta": {
    "dataset": "tmall"
  }
}
```

- data[].product_id (string): Stable Tmall product identifier used for exact filtering and paired with product_url.
- data[].title (string): Product title recorded for the month; it is returned for display and grouping, but it is not a direct query_metrics or query_details filter. Use search_products for title lookup.
- data[].product_url (string): Canonical Tmall product-detail URL generated from product_id.
- data[].shop_id (string): Stable Tmall shop identifier used for exact filtering and paired with shop_url.
- data[].shop_url (string): Canonical Tmall shop-page URL generated from shop_id.
- data[].brand (string): Brand name recorded by the upstream Tmall data, paired with brand_id; it may be missing or vary in spelling.
- data[].category_l1 (string): Level-1 category name in the upstream Tmall hierarchy, paired with category_l1_id.
- data[].category_l2 (string): Level-2 category name in the upstream Tmall hierarchy, paired with category_l2_id.
- data[].category_l3 (string): Level-3 category name in the upstream Tmall hierarchy, paired with category_l3_id.
- data[].shop (string): Shop name recorded by Tmall, paired with shop_id; it may change over time.
- data[].month (time): Calendar month to which the product sales record belongs, formatted as YYYY-MM; the dataset grain is monthly.
- data[].is_live (string): Whether the product has appeared in live commerce during the record month; null or empty means unknown, not no.
- data[].has_bybt (string): Whether the product participates in the RMB 10B subsidy program during the record month; null or empty means unknown, not no.
- data[].bc_type (string): Tmall B/C shop type after trimming blank values; null means the type is unknown.
- data[].gmv (number): Post-coupon sales amount in CNY; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
- data[].units (number): Units sold; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
- data[].asp (number): Weighted average selling price in CNY, calculated as SUM(gmv) / SUM(units); null when total units is zero, and available only in aggregate queries.
## POST /v1/quote

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Optional REST cost preview; actual execution determines billing. MCP previews use query_metrics with dry_run=true.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "filters": {
          "description": "Query-specific filters; shared scope belongs in common_filters.",
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        "group_by": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "limit": {
          "default": 100,
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "metrics": {
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        "order_by": {
          "items": {
            "$ref": "#/$defs/Schema2"
          },
          "type": "array"
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema4"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Omit to inherit the main query time; provide for cross-period analysis."
        }
      },
      "required": [
        "name",
        "metrics"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "dir": {
          "default": "asc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "field": {
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "Schema3": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema4": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "description": "One flat request shape that FastMCP can expose as tool arguments.",
  "properties": {
    "additional_queries": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Schema1"
          },
          "maxItems": 3,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "common_filters": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "filters": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "group_by": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "limit": {
      "anyOf": [
        {
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "main_query_name": {
      "anyOf": [
        {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional ASCII bundle result name. Omit for single metric quotes."
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "metrics": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "order_by": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Schema2"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    },
    "time": {
      "anyOf": [
        {
          "$ref": "#/$defs/Schema4"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    }
  },
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "group_by": [
    "brand"
  ],
  "limit": 10,
  "metrics": [
    "gmv"
  ],
  "order_by": [
    {
      "dir": "desc",
      "field": "gmv"
    }
  ],
  "task_query": "查看天猫最近一个完整月的品牌销售额排名",
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

```json
{}
```

- upper_bound_credits (integer): No field description available
## POST /v1/search_values

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "type": "string"
        },
        "kw": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "limit": {
          "default": 20,
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        }
      },
      "required": [
        "name",
        "field"
      ],
      "type": "object"
    }
  },
  "properties": {
    "additional_searches": {
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "default": false,
      "description": "Set true only when the user asks for a price preview.",
      "type": "boolean"
    },
    "field": {
      "description": "Searchable field for a user-supplied name. category searches every category level. Exact IDs and URLs are ready to query.",
      "type": "string"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "MCP paid non-dry-run single operations require idempotency_key; REST and free previews may omit it. Bundles reject idempotency_key; omit it with additional_searches or field=category, which expands into category levels. Recover failed items as single concrete-field operations."
    },
    "kw": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "limit": {
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "dataset",
    "field"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "field": "brand",
  "kw": "example",
  "limit": 10
}
```

### Synthetic response / 合成响应

```json
{
  "data": []
}
```

- data (array<object>): No field description available
## search_values

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "type": "string"
        },
        "kw": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "limit": {
          "default": 20,
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        }
      },
      "required": [
        "name",
        "field"
      ],
      "type": "object"
    }
  },
  "properties": {
    "additional_searches": {
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "default": false,
      "description": "Set true only when the user asks for a price preview.",
      "type": "boolean"
    },
    "field": {
      "description": "Searchable field for a user-supplied name. category searches every category level. Exact IDs and URLs are ready to query.",
      "type": "string"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "MCP paid non-dry-run single operations require idempotency_key; REST and free previews may omit it. Bundles reject idempotency_key; omit it with additional_searches or field=category, which expands into category levels. Recover failed items as single concrete-field operations."
    },
    "kw": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "limit": {
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "dataset",
    "field"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "field": "brand",
  "idempotency_key": "directory-example",
  "kw": "example",
  "limit": 10
}
```

### Synthetic response / 合成响应

```json
{
  "data": []
}
```

- data (array<object>): No field description available
## asklear search-values

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "type": "string"
        },
        "kw": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "limit": {
          "default": 20,
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        }
      },
      "required": [
        "name",
        "field"
      ],
      "type": "object"
    }
  },
  "properties": {
    "additional_searches": {
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "default": false,
      "description": "Set true only when the user asks for a price preview.",
      "type": "boolean"
    },
    "field": {
      "description": "Searchable field for a user-supplied name. category searches every category level. Exact IDs and URLs are ready to query.",
      "type": "string"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "MCP paid non-dry-run single operations require idempotency_key; REST and free previews may omit it. Bundles reject idempotency_key; omit it with additional_searches or field=category, which expands into category levels. Recover failed items as single concrete-field operations."
    },
    "kw": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "limit": {
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "dataset",
    "field"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "field": "brand",
  "idempotency_key": "directory-example",
  "kw": "example",
  "limit": 10
}
```

### Synthetic response / 合成响应

```json
{
  "data": []
}
```

- data (array<object>): No field description available
## POST /v1/query_details

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "fields": {
      "description": "Raw detail output fields. Use query_metrics for rankings and product or shop links.",
      "items": {
        "enum": [
          "product_id",
          "title",
          "product_url",
          "shop_id",
          "shop_url",
          "brand_id",
          "brand",
          "category_l1_id",
          "category_l1",
          "category_l2_id",
          "category_l2",
          "category_l3_id",
          "category_l3",
          "shop",
          "specification",
          "month",
          "is_live",
          "has_bybt",
          "bc_type",
          "gmv",
          "units"
        ]
      },
      "maxItems": 34,
      "minItems": 1,
      "type": "array"
    },
    "filters": {
      "description": "Raw detail-field filters for a tightly scoped drilldown.",
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "type": "array"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "MCP paid non-dry-run single operations require idempotency_key; REST and free previews may omit it."
    },
    "limit": {
      "default": 100,
      "maximum": 1000,
      "minimum": 1,
      "type": "integer"
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    },
    "time": {
      "$ref": "#/$defs/Schema2"
    }
  },
  "required": [
    "dataset",
    "fields",
    "time"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "fields": [
    "product_id",
    "title",
    "product_url"
  ],
  "filters": [
    {
      "field": "product_id",
      "op": "eq",
      "value": "1234567890"
    }
  ],
  "limit": 10,
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

```json
{
  "data": []
}
```

- data[].product_id (string): Stable Tmall product identifier used for exact filtering and paired with product_url.
- data[].title (string): Product title recorded for the month; it is returned for display and grouping, but it is not a direct query_metrics or query_details filter. Use search_products for title lookup.
- data[].product_url (string): Canonical Tmall product-detail URL generated from product_id.
- data[].shop_id (string): Stable Tmall shop identifier used for exact filtering and paired with shop_url.
- data[].shop_url (string): Canonical Tmall shop-page URL generated from shop_id.
- data[].brand_id (string): Upstream Tmall brand identifier paired with brand; it may be missing when the source does not identify a brand.
- data[].brand (string): Brand name recorded by the upstream Tmall data, paired with brand_id; it may be missing or vary in spelling.
- data[].category_l1_id (string): Identifier of category_l1 in the upstream Tmall category hierarchy; it may be missing.
- data[].category_l1 (string): Level-1 category name in the upstream Tmall hierarchy, paired with category_l1_id.
- data[].category_l2_id (string): Identifier of category_l2 in the upstream Tmall category hierarchy; it may be missing.
- data[].category_l2 (string): Level-2 category name in the upstream Tmall hierarchy, paired with category_l2_id.
- data[].category_l3_id (string): Identifier of category_l3 in the upstream Tmall category hierarchy; it may be missing.
- data[].category_l3 (string): Level-3 category name in the upstream Tmall hierarchy, paired with category_l3_id.
- data[].shop (string): Shop name recorded by Tmall, paired with shop_id; it may change over time.
- data[].specification (string): Product specification attributes, usually encoded as a JSON object string; keys vary by category, the value may be empty, and it is available only in detail output.
- data[].month (time): Calendar month to which the product sales record belongs, formatted as YYYY-MM; the dataset grain is monthly.
- data[].is_live (string): Whether the product has appeared in live commerce during the record month; null or empty means unknown, not no.
- data[].has_bybt (string): Whether the product participates in the RMB 10B subsidy program during the record month; null or empty means unknown, not no.
- data[].bc_type (string): Tmall B/C shop type after trimming blank values; null means the type is unknown.
- data[].gmv (number): Post-coupon sales amount in CNY; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
- data[].units (number): Units sold; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
## query_details

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "fields": {
      "description": "Raw detail output fields. Use query_metrics for rankings and product or shop links.",
      "items": {
        "enum": [
          "product_id",
          "title",
          "product_url",
          "shop_id",
          "shop_url",
          "brand_id",
          "brand",
          "category_l1_id",
          "category_l1",
          "category_l2_id",
          "category_l2",
          "category_l3_id",
          "category_l3",
          "shop",
          "specification",
          "month",
          "is_live",
          "has_bybt",
          "bc_type",
          "gmv",
          "units"
        ]
      },
      "maxItems": 34,
      "minItems": 1,
      "type": "array"
    },
    "filters": {
      "description": "Raw detail-field filters for a tightly scoped drilldown.",
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "type": "array"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "MCP paid non-dry-run single operations require idempotency_key; REST and free previews may omit it."
    },
    "limit": {
      "default": 100,
      "maximum": 1000,
      "minimum": 1,
      "type": "integer"
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    },
    "time": {
      "$ref": "#/$defs/Schema2"
    }
  },
  "required": [
    "dataset",
    "fields",
    "time"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "fields": [
    "product_id",
    "title",
    "product_url"
  ],
  "filters": [
    {
      "field": "product_id",
      "op": "eq",
      "value": "1234567890"
    }
  ],
  "idempotency_key": "directory-example",
  "limit": 10,
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

```json
{
  "data": []
}
```

- data[].product_id (string): Stable Tmall product identifier used for exact filtering and paired with product_url.
- data[].title (string): Product title recorded for the month; it is returned for display and grouping, but it is not a direct query_metrics or query_details filter. Use search_products for title lookup.
- data[].product_url (string): Canonical Tmall product-detail URL generated from product_id.
- data[].shop_id (string): Stable Tmall shop identifier used for exact filtering and paired with shop_url.
- data[].shop_url (string): Canonical Tmall shop-page URL generated from shop_id.
- data[].brand_id (string): Upstream Tmall brand identifier paired with brand; it may be missing when the source does not identify a brand.
- data[].brand (string): Brand name recorded by the upstream Tmall data, paired with brand_id; it may be missing or vary in spelling.
- data[].category_l1_id (string): Identifier of category_l1 in the upstream Tmall category hierarchy; it may be missing.
- data[].category_l1 (string): Level-1 category name in the upstream Tmall hierarchy, paired with category_l1_id.
- data[].category_l2_id (string): Identifier of category_l2 in the upstream Tmall category hierarchy; it may be missing.
- data[].category_l2 (string): Level-2 category name in the upstream Tmall hierarchy, paired with category_l2_id.
- data[].category_l3_id (string): Identifier of category_l3 in the upstream Tmall category hierarchy; it may be missing.
- data[].category_l3 (string): Level-3 category name in the upstream Tmall hierarchy, paired with category_l3_id.
- data[].shop (string): Shop name recorded by Tmall, paired with shop_id; it may change over time.
- data[].specification (string): Product specification attributes, usually encoded as a JSON object string; keys vary by category, the value may be empty, and it is available only in detail output.
- data[].month (time): Calendar month to which the product sales record belongs, formatted as YYYY-MM; the dataset grain is monthly.
- data[].is_live (string): Whether the product has appeared in live commerce during the record month; null or empty means unknown, not no.
- data[].has_bybt (string): Whether the product participates in the RMB 10B subsidy program during the record month; null or empty means unknown, not no.
- data[].bc_type (string): Tmall B/C shop type after trimming blank values; null means the type is unknown.
- data[].gmv (number): Post-coupon sales amount in CNY; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
- data[].units (number): Units sold; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
## asklear query-details

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a confirmed HTTPS Taobao product URL.
Shop filters in metric/detail queries require exact IDs or confirmed HTTPS Taobao URLs.
NULL and empty strings consistently mean unknown, not no.

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "fields": {
      "description": "Raw detail output fields. Use query_metrics for rankings and product or shop links.",
      "items": {
        "enum": [
          "product_id",
          "title",
          "product_url",
          "shop_id",
          "shop_url",
          "brand_id",
          "brand",
          "category_l1_id",
          "category_l1",
          "category_l2_id",
          "category_l2",
          "category_l3_id",
          "category_l3",
          "shop",
          "specification",
          "month",
          "is_live",
          "has_bybt",
          "bc_type",
          "gmv",
          "units"
        ]
      },
      "maxItems": 34,
      "minItems": 1,
      "type": "array"
    },
    "filters": {
      "description": "Raw detail-field filters for a tightly scoped drilldown.",
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "type": "array"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "MCP paid non-dry-run single operations require idempotency_key; REST and free previews may omit it."
    },
    "limit": {
      "default": 100,
      "maximum": 1000,
      "minimum": 1,
      "type": "integer"
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    },
    "time": {
      "$ref": "#/$defs/Schema2"
    }
  },
  "required": [
    "dataset",
    "fields",
    "time"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "fields": [
    "product_id",
    "title",
    "product_url"
  ],
  "filters": [
    {
      "field": "product_id",
      "op": "eq",
      "value": "1234567890"
    }
  ],
  "idempotency_key": "directory-example",
  "limit": 10,
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

```json
{
  "data": []
}
```

- data[].product_id (string): Stable Tmall product identifier used for exact filtering and paired with product_url.
- data[].title (string): Product title recorded for the month; it is returned for display and grouping, but it is not a direct query_metrics or query_details filter. Use search_products for title lookup.
- data[].product_url (string): Canonical Tmall product-detail URL generated from product_id.
- data[].shop_id (string): Stable Tmall shop identifier used for exact filtering and paired with shop_url.
- data[].shop_url (string): Canonical Tmall shop-page URL generated from shop_id.
- data[].brand_id (string): Upstream Tmall brand identifier paired with brand; it may be missing when the source does not identify a brand.
- data[].brand (string): Brand name recorded by the upstream Tmall data, paired with brand_id; it may be missing or vary in spelling.
- data[].category_l1_id (string): Identifier of category_l1 in the upstream Tmall category hierarchy; it may be missing.
- data[].category_l1 (string): Level-1 category name in the upstream Tmall hierarchy, paired with category_l1_id.
- data[].category_l2_id (string): Identifier of category_l2 in the upstream Tmall category hierarchy; it may be missing.
- data[].category_l2 (string): Level-2 category name in the upstream Tmall hierarchy, paired with category_l2_id.
- data[].category_l3_id (string): Identifier of category_l3 in the upstream Tmall category hierarchy; it may be missing.
- data[].category_l3 (string): Level-3 category name in the upstream Tmall hierarchy, paired with category_l3_id.
- data[].shop (string): Shop name recorded by Tmall, paired with shop_id; it may change over time.
- data[].specification (string): Product specification attributes, usually encoded as a JSON object string; keys vary by category, the value may be empty, and it is available only in detail output.
- data[].month (time): Calendar month to which the product sales record belongs, formatted as YYYY-MM; the dataset grain is monthly.
- data[].is_live (string): Whether the product has appeared in live commerce during the record month; null or empty means unknown, not no.
- data[].has_bybt (string): Whether the product participates in the RMB 10B subsidy program during the record month; null or empty means unknown, not no.
- data[].bc_type (string): Tmall B/C shop type after trimming blank values; null means the type is unknown.
- data[].gmv (number): Post-coupon sales amount in CNY; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.
- data[].units (number): Units sold; aggregate queries sum the selected scope, while detail queries return the value for one product-month record.