# 天猫商品月度销量明细表

天猫商品月度销量，公开直播、百亿补贴与 B/C 店铺明细。

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

catalog_version: 5c920c774a55e44d7e8c709143b88a18b8b2afcef91a5d19a8c9ae5d565d9077
updated_at: 2026-10-21T12:06:16.523771+00:00

仅天猫

历史数据以数据集发布版本定义覆盖周期；实时读取反映请求时资料，不保证覆盖全部记录。

Docs: https://docs.asklear.cn/capabilities/dataset%3Atmall

## GET /v1/datasets/tmall

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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>): 暂无字段说明
- metrics (array<object>): 暂无字段说明
## describe

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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>): 暂无字段说明
- metrics (array<object>): 暂无字段说明
## asklear describe

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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>): 暂无字段说明
- metrics (array<object>): 暂无字段说明
## GET /v1/datasets/tmall/sample

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

Example row shape only; samples are not analytical evidence.

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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>): 暂无字段说明
## sample_rows

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

Example row shape only; samples are not analytical evidence.

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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>): 暂无字段说明
## asklear sample

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

Example row shape only; samples are not analytical evidence.

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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>): 暂无字段说明
## POST /v1/query_metrics

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

遵循现有数据集查询计费及账号授权。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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): 天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。
- data[].title (string): 该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].product_url (string): 根据 product_id 生成的标准天猫商品详情页链接。
- data[].shop_id (string): 天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。
- data[].shop_url (string): 根据 shop_id 生成的标准天猫店铺页面链接。
- data[].brand (string): 天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。
- data[].category_l1 (string): 天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。
- data[].category_l2 (string): 天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。
- data[].category_l3 (string): 天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。
- data[].shop (string): 天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。
- data[].month (time): 商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。
- data[].is_live (string): 商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。
- data[].has_bybt (string): 商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。
- data[].bc_type (string): 天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。
- data[].gmv (number): 券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。
- data[].units (number): 商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。
- data[].asp (number): 加权平均成交价，单位为人民币元，按 SUM(gmv) / SUM(units) 计算；总销量为 0 时返回空，仅支持聚合查询。
## query_metrics

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

遵循现有数据集查询计费及账号授权。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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): 天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。
- data[].title (string): 该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].product_url (string): 根据 product_id 生成的标准天猫商品详情页链接。
- data[].shop_id (string): 天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。
- data[].shop_url (string): 根据 shop_id 生成的标准天猫店铺页面链接。
- data[].brand (string): 天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。
- data[].category_l1 (string): 天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。
- data[].category_l2 (string): 天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。
- data[].category_l3 (string): 天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。
- data[].shop (string): 天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。
- data[].month (time): 商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。
- data[].is_live (string): 商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。
- data[].has_bybt (string): 商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。
- data[].bc_type (string): 天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。
- data[].gmv (number): 券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。
- data[].units (number): 商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。
- data[].asp (number): 加权平均成交价，单位为人民币元，按 SUM(gmv) / SUM(units) 计算；总销量为 0 时返回空，仅支持聚合查询。
## asklear query

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

遵循现有数据集查询计费及账号授权。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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): 天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。
- data[].title (string): 该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].product_url (string): 根据 product_id 生成的标准天猫商品详情页链接。
- data[].shop_id (string): 天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。
- data[].shop_url (string): 根据 shop_id 生成的标准天猫店铺页面链接。
- data[].brand (string): 天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。
- data[].category_l1 (string): 天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。
- data[].category_l2 (string): 天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。
- data[].category_l3 (string): 天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。
- data[].shop (string): 天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。
- data[].month (time): 商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。
- data[].is_live (string): 商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。
- data[].has_bybt (string): 商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。
- data[].bc_type (string): 天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。
- data[].gmv (number): 券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。
- data[].units (number): 商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。
- data[].asp (number): 加权平均成交价，单位为人民币元，按 SUM(gmv) / SUM(units) 计算；总销量为 0 时返回空，仅支持聚合查询。
## POST /v1/quote

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

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

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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): 暂无字段说明
## POST /v1/search_values

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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>): 暂无字段说明
## search_values

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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>): 暂无字段说明
## asklear search-values

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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>): 暂无字段说明
## POST /v1/query_details

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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): 天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。
- data[].title (string): 该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].product_url (string): 根据 product_id 生成的标准天猫商品详情页链接。
- data[].shop_id (string): 天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。
- data[].shop_url (string): 根据 shop_id 生成的标准天猫店铺页面链接。
- data[].brand_id (string): 天猫上游提供的品牌标识，与 brand 对应；上游未识别品牌时可能为空。
- data[].brand (string): 天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。
- data[].category_l1_id (string): 天猫上游品类体系中 category_l1 对应的一级品类标识；可能为空。
- data[].category_l1 (string): 天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。
- data[].category_l2_id (string): 天猫上游品类体系中 category_l2 对应的二级品类标识；可能为空。
- data[].category_l2 (string): 天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。
- data[].category_l3_id (string): 天猫上游品类体系中 category_l3 对应的三级品类标识；可能为空。
- data[].category_l3 (string): 天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。
- data[].shop (string): 天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。
- data[].specification (string): 商品规格属性集合，通常编码为 JSON 对象字符串；属性键因品类而异，内容可能为空，仅支持明细返回。
- data[].month (time): 商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。
- data[].is_live (string): 商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。
- data[].has_bybt (string): 商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。
- data[].bc_type (string): 天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。
- data[].gmv (number): 券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。
- data[].units (number): 商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。
## query_details

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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): 天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。
- data[].title (string): 该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].product_url (string): 根据 product_id 生成的标准天猫商品详情页链接。
- data[].shop_id (string): 天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。
- data[].shop_url (string): 根据 shop_id 生成的标准天猫店铺页面链接。
- data[].brand_id (string): 天猫上游提供的品牌标识，与 brand 对应；上游未识别品牌时可能为空。
- data[].brand (string): 天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。
- data[].category_l1_id (string): 天猫上游品类体系中 category_l1 对应的一级品类标识；可能为空。
- data[].category_l1 (string): 天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。
- data[].category_l2_id (string): 天猫上游品类体系中 category_l2 对应的二级品类标识；可能为空。
- data[].category_l2 (string): 天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。
- data[].category_l3_id (string): 天猫上游品类体系中 category_l3 对应的三级品类标识；可能为空。
- data[].category_l3 (string): 天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。
- data[].shop (string): 天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。
- data[].specification (string): 商品规格属性集合，通常编码为 JSON 对象字符串；属性键因品类而异，内容可能为空，仅支持明细返回。
- data[].month (time): 商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。
- data[].is_live (string): 商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。
- data[].has_bybt (string): 商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。
- data[].bc_type (string): 天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。
- data[].gmv (number): 券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。
- data[].units (number): 商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。
## asklear query-details

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或已确认的 HTTPS 淘宝商品链接
店铺在指标/明细查询中只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
NULL 和空字符串统一表示未知，不等同于否

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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): 天猫商品的稳定标识，用于精确筛选，并与 product_url 对应。
- data[].title (string): 该自然月记录的商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].product_url (string): 根据 product_id 生成的标准天猫商品详情页链接。
- data[].shop_id (string): 天猫店铺的稳定标识，用于精确筛选，并与 shop_url 对应。
- data[].shop_url (string): 根据 shop_id 生成的标准天猫店铺页面链接。
- data[].brand_id (string): 天猫上游提供的品牌标识，与 brand 对应；上游未识别品牌时可能为空。
- data[].brand (string): 天猫上游记录的品牌名称，与 brand_id 对应；可能为空，也可能存在名称写法差异。
- data[].category_l1_id (string): 天猫上游品类体系中 category_l1 对应的一级品类标识；可能为空。
- data[].category_l1 (string): 天猫上游品类体系中的一级品类名称，与 category_l1_id 对应。
- data[].category_l2_id (string): 天猫上游品类体系中 category_l2 对应的二级品类标识；可能为空。
- data[].category_l2 (string): 天猫上游品类体系中的二级品类名称，与 category_l2_id 对应。
- data[].category_l3_id (string): 天猫上游品类体系中 category_l3 对应的三级品类标识；可能为空。
- data[].category_l3 (string): 天猫上游品类体系中的三级品类名称，与 category_l3_id 对应。
- data[].shop (string): 天猫记录的店铺名称，与 shop_id 对应；名称可能随时间变化。
- data[].specification (string): 商品规格属性集合，通常编码为 JSON 对象字符串；属性键因品类而异，内容可能为空，仅支持明细返回。
- data[].month (time): 商品销售记录所属自然月，格式为 YYYY-MM；该数据集为月粒度。
- data[].is_live (string): 商品是否上过直播；指记录月份内是否出现在天猫直播场景；空值或空字符串表示未知，不表示否。
- data[].has_bybt (string): 商品是否参加百亿补贴；指记录月份内是否参加天猫百亿补贴；空值或空字符串表示未知，不表示否。
- data[].bc_type (string): 天猫店铺 B/C 类标识；去除空白后使用，空值表示店铺类型未知。
- data[].gmv (number): 券后销售额，单位为人民币元；聚合查询返回所选范围合计，明细查询返回单条商品月记录的金额。
- data[].units (number): 商品销量；聚合查询返回所选范围合计，明细查询返回单条商品月记录的销量。
## POST /v1/search_products

legacy · available · api_key, oauth

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

仅返回商品身份；实际调用检查服务状态及账号授权。

执行遵循现有计价；读取公开说明不扣 Credits。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### 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"
    }
  },
  "additionalProperties": false,
  "description": "Bounded request for resolving a product title to public identities.",
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "tmall"
    },
    "dry_run": {
      "default": false,
      "description": "Return a price preview without executing or charging.",
      "type": "boolean"
    },
    "filters": {
      "description": "Optional brand, category, or shop filters. Only eq and in are supported.",
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 8,
      "type": "array"
    },
    "idempotency_key": {
      "anyOf": [
        {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional REST key; MCP paid calls keep the existing idempotency rule."
    },
    "limit": {
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "query": {
      "description": "Product title fragment to match.",
      "maxLength": 128,
      "minLength": 1,
      "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
    },
    "time": {
      "anyOf": [
        {
          "$ref": "#/$defs/Schema2"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional monthly range. Omit to use the latest authorized complete month."
    }
  },
  "required": [
    "dataset",
    "query"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "dataset": "tmall",
  "limit": 10,
  "query": "example",
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

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

- data[].product_id (string): 暂无字段说明
- data[].title (string): 暂无字段说明
- data[].product_url (string): 暂无字段说明
- data[].brand (string): 暂无字段说明
- data[].category_l1 (string): 暂无字段说明
- data[].category_l2 (string): 暂无字段说明
- data[].category_l3 (string): 暂无字段说明
- data[].shop (string): 暂无字段说明
- data[].available_months (array<string>): 暂无字段说明

Follow up: GET /v1/search_products/{query_id}
Read an existing product search result.

## POST /v1/agent/run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

天猫同步读取需要 API Key；遵循数据集授权及现有查询计费。

使用现有天猫查询价目表，由查询应用结算。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema10": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema10"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema10"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema11": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema12": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema10"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "properties": {
        "filters": {
          "description": "Query-specific filters; shared scope belongs in common_filters.",
          "items": {
            "$ref": "#/$defs/Schema6"
          },
          "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/Schema5"
          },
          "type": "array"
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema7"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Omit to inherit the main query time; provide for cross-period analysis."
        }
      },
      "required": [
        "name",
        "metrics"
      ],
      "type": "object"
    },
    "Schema5": {
      "properties": {
        "dir": {
          "default": "asc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "field": {
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "Schema6": {
      "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"
    },
    "Schema7": {
      "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"
    },
    "Schema8": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema9": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "properties": {
        "additional_queries": {
          "description": "Up to three additional analyses for shares, comparisons, or multiple views.",
          "items": {
            "$ref": "#/$defs/Schema4"
          },
          "maxItems": 3,
          "type": "array"
        },
        "common_filters": {
          "description": "Filters applied to every query in the bundle.",
          "items": {
            "$ref": "#/$defs/Schema6"
          },
          "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/Schema6"
          },
          "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": {
            "type": "string"
          },
          "type": "array"
        },
        "idempotency_key": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Native run requires an outer idempotency_key that binds the entire single or non-atomic bundle request. Keep it on a network retry; replay returns existing result links without rerunning failed bundle items."
        },
        "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": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "order_by": {
          "description": "Sort by a returned metric or groupable dimension.",
          "items": {
            "$ref": "#/$defs/Schema5"
          },
          "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/Schema7",
          "description": "Absolute range or last_complete_months; relative time needs no describe."
        }
      },
      "required": [
        "dataset",
        "metrics",
        "time"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "query_metrics"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall",
    "group_by": [
      "brand"
    ],
    "limit": 10,
    "metrics": [
      "gmv"
    ],
    "time": {
      "last_complete_months": 1
    }
  },
  "operation": "query_metrics"
}
```

### Synthetic response / 合成响应

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

- compiled (boolean): 暂无字段说明
- data (array): 暂无字段说明
- estimate (object): 暂无字段说明
- meta (object): 暂无字段说明
- plan_digest (string): 暂无字段说明
- results (array): 暂无字段说明
## run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

天猫同步读取需要 API Key；遵循数据集授权及现有查询计费。

使用现有天猫查询价目表，由查询应用结算。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema10": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema10"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema10"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema11": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema12": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema10"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "properties": {
        "filters": {
          "description": "Query-specific filters; shared scope belongs in common_filters.",
          "items": {
            "$ref": "#/$defs/Schema6"
          },
          "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/Schema5"
          },
          "type": "array"
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema7"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Omit to inherit the main query time; provide for cross-period analysis."
        }
      },
      "required": [
        "name",
        "metrics"
      ],
      "type": "object"
    },
    "Schema5": {
      "properties": {
        "dir": {
          "default": "asc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "field": {
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "Schema6": {
      "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"
    },
    "Schema7": {
      "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"
    },
    "Schema8": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema9": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "properties": {
        "additional_queries": {
          "description": "Up to three additional analyses for shares, comparisons, or multiple views.",
          "items": {
            "$ref": "#/$defs/Schema4"
          },
          "maxItems": 3,
          "type": "array"
        },
        "common_filters": {
          "description": "Filters applied to every query in the bundle.",
          "items": {
            "$ref": "#/$defs/Schema6"
          },
          "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/Schema6"
          },
          "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": {
            "type": "string"
          },
          "type": "array"
        },
        "idempotency_key": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Native run requires an outer idempotency_key that binds the entire single or non-atomic bundle request. Keep it on a network retry; replay returns existing result links without rerunning failed bundle items."
        },
        "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": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "order_by": {
          "description": "Sort by a returned metric or groupable dimension.",
          "items": {
            "$ref": "#/$defs/Schema5"
          },
          "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/Schema7",
          "description": "Absolute range or last_complete_months; relative time needs no describe."
        }
      },
      "required": [
        "dataset",
        "metrics",
        "time"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "query_metrics"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "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
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall",
    "group_by": [
      "brand"
    ],
    "limit": 10,
    "metrics": [
      "gmv"
    ],
    "time": {
      "last_complete_months": 1
    }
  },
  "operation": "query_metrics"
}
```

### Synthetic response / 合成响应

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

- compiled (boolean): 暂无字段说明
- data (array): 暂无字段说明
- estimate (object): 暂无字段说明
- meta (object): 暂无字段说明
- plan_digest (string): 暂无字段说明
- results (array): 暂无字段说明
## POST /v1/agent/run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

天猫数据查询需要 API Key；遵循数据集授权及查询价目表。

使用 Asklear 数据查询价目表结算。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema10": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema8"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "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"
    },
    "Schema5": {
      "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"
    },
    "Schema6": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema7": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema8": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema8"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema8"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema9": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "properties": {
        "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": {
            "type": "string"
          },
          "maxItems": 34,
          "minItems": 1,
          "type": "array"
        },
        "filters": {
          "description": "Raw detail-field filters for a tightly scoped drilldown.",
          "items": {
            "$ref": "#/$defs/Schema4"
          },
          "type": "array"
        },
        "idempotency_key": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Native execution binds the complete request to the outer idempotency_key."
        },
        "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/Schema5"
        }
      },
      "required": [
        "dataset",
        "fields",
        "time"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "query_details"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall",
    "fields": [
      "product_id"
    ],
    "limit": 10,
    "time": {
      "last_complete_months": 1
    }
  },
  "operation": "query_details"
}
```

### Synthetic response / 合成响应

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

- billing (object): 暂无字段说明
- compiled (boolean): 暂无字段说明
- data (array): 暂无字段说明
- estimate (object): 暂无字段说明
- meta (object): 暂无字段说明
- plan_digest (string): 暂无字段说明
- results (array): 暂无字段说明
## run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

天猫数据查询需要 API Key；遵循数据集授权及查询价目表。

使用 Asklear 数据查询价目表结算。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema10": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema8"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "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"
    },
    "Schema5": {
      "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"
    },
    "Schema6": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema7": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema8": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema8"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema8"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema9": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "properties": {
        "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": {
            "type": "string"
          },
          "maxItems": 34,
          "minItems": 1,
          "type": "array"
        },
        "filters": {
          "description": "Raw detail-field filters for a tightly scoped drilldown.",
          "items": {
            "$ref": "#/$defs/Schema4"
          },
          "type": "array"
        },
        "idempotency_key": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Native execution binds the complete request to the outer idempotency_key."
        },
        "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/Schema5"
        }
      },
      "required": [
        "dataset",
        "fields",
        "time"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "query_details"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "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
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall",
    "fields": [
      "product_id"
    ],
    "limit": 10,
    "time": {
      "last_complete_months": 1
    }
  },
  "operation": "query_details"
}
```

### Synthetic response / 合成响应

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

- billing (object): 暂无字段说明
- compiled (boolean): 暂无字段说明
- data (array): 暂无字段说明
- estimate (object): 暂无字段说明
- meta (object): 暂无字段说明
- plan_digest (string): 暂无字段说明
- results (array): 暂无字段说明
## POST /v1/agent/run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

天猫数据查询需要 API Key；遵循数据集授权及查询价目表。

使用 Asklear 数据查询价目表结算。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "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"
    },
    "Schema5": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema6": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema7": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema7"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema7"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema8": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema9": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema7"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "properties": {
        "additional_searches": {
          "items": {
            "$ref": "#/$defs/Schema4"
          },
          "maxItems": 3,
          "type": "array"
        },
        "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": "Native execution binds the complete request to the outer idempotency_key."
        },
        "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"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "search_values"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall",
    "field": "brand",
    "kw": null,
    "limit": 20
  },
  "operation": "search_values"
}
```

### Synthetic response / 合成响应

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

- billing (object): 暂无字段说明
- candidate_count (integer): 暂无字段说明
- compiled (boolean): 暂无字段说明
- data (array): 暂无字段说明
- estimate (object): 暂无字段说明
- field (string): 暂无字段说明
- keyword (string|null): 暂无字段说明
- matches (array): 暂无字段说明
- meta (object): 暂无字段说明
- plan_digest (string): 暂无字段说明
- requires_clarification (boolean): 暂无字段说明
- results (array): 暂无字段说明
- status (string): 暂无字段说明
- values (array): 暂无字段说明
## run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

天猫数据查询需要 API Key；遵循数据集授权及查询价目表。

使用 Asklear 数据查询价目表结算。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "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"
    },
    "Schema5": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema6": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema7": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema7"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema7"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema8": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema9": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema7"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "properties": {
        "additional_searches": {
          "items": {
            "$ref": "#/$defs/Schema4"
          },
          "maxItems": 3,
          "type": "array"
        },
        "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": "Native execution binds the complete request to the outer idempotency_key."
        },
        "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"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "search_values"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "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
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall",
    "field": "brand",
    "kw": null,
    "limit": 20
  },
  "operation": "search_values"
}
```

### Synthetic response / 合成响应

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

- billing (object): 暂无字段说明
- candidate_count (integer): 暂无字段说明
- compiled (boolean): 暂无字段说明
- data (array): 暂无字段说明
- estimate (object): 暂无字段说明
- field (string): 暂无字段说明
- keyword (string|null): 暂无字段说明
- matches (array): 暂无字段说明
- meta (object): 暂无字段说明
- plan_digest (string): 暂无字段说明
- requires_clarification (boolean): 暂无字段说明
- results (array): 暂无字段说明
- status (string): 暂无字段说明
- values (array): 暂无字段说明
## POST /v1/agent/run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

天猫数据查询需要 API Key；遵循数据集授权及查询价目表。

使用 Asklear 数据查询价目表结算。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema10": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema8"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "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"
    },
    "Schema5": {
      "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"
    },
    "Schema6": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema7": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema8": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema8"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema8"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema9": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "additionalProperties": false,
      "description": "Bounded request for resolving a product title to public identities.",
      "properties": {
        "dataset": {
          "const": "tmall"
        },
        "dry_run": {
          "default": false,
          "description": "Return a price preview without executing or charging.",
          "type": "boolean"
        },
        "filters": {
          "description": "Optional brand, category, or shop filters. Only eq and in are supported.",
          "items": {
            "$ref": "#/$defs/Schema4"
          },
          "maxItems": 8,
          "type": "array"
        },
        "idempotency_key": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Native execution binds the complete request to the outer idempotency_key."
        },
        "limit": {
          "default": 20,
          "maximum": 50,
          "minimum": 1,
          "type": "integer"
        },
        "max_credits": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "query": {
          "description": "Product title fragment to match.",
          "maxLength": 128,
          "minLength": 1,
          "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
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema5"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional monthly range. Omit to use the latest authorized complete month."
        }
      },
      "required": [
        "dataset",
        "query"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "search_products"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall",
    "limit": 10,
    "query": "sample"
  },
  "operation": "search_products"
}
```

### Synthetic response / 合成响应

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

- billing (object): 暂无字段说明
- compiled (boolean): 暂无字段说明
- data (array): 暂无字段说明
- estimate (object): 暂无字段说明
- meta (object): 暂无字段说明
- plan_digest (string): 暂无字段说明
- results (array): 暂无字段说明
## run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

天猫数据查询需要 API Key；遵循数据集授权及查询价目表。

使用 Asklear 数据查询价目表结算。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema10": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema8"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "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"
    },
    "Schema5": {
      "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"
    },
    "Schema6": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema7": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema8": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema8"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema8"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema9": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "additionalProperties": false,
      "description": "Bounded request for resolving a product title to public identities.",
      "properties": {
        "dataset": {
          "const": "tmall"
        },
        "dry_run": {
          "default": false,
          "description": "Return a price preview without executing or charging.",
          "type": "boolean"
        },
        "filters": {
          "description": "Optional brand, category, or shop filters. Only eq and in are supported.",
          "items": {
            "$ref": "#/$defs/Schema4"
          },
          "maxItems": 8,
          "type": "array"
        },
        "idempotency_key": {
          "anyOf": [
            {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Native execution binds the complete request to the outer idempotency_key."
        },
        "limit": {
          "default": 20,
          "maximum": 50,
          "minimum": 1,
          "type": "integer"
        },
        "max_credits": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "query": {
          "description": "Product title fragment to match.",
          "maxLength": 128,
          "minLength": 1,
          "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
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema5"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional monthly range. Omit to use the latest authorized complete month."
        }
      },
      "required": [
        "dataset",
        "query"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "search_products"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "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
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall",
    "limit": 10,
    "query": "sample"
  },
  "operation": "search_products"
}
```

### Synthetic response / 合成响应

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

- billing (object): 暂无字段说明
- compiled (boolean): 暂无字段说明
- data (array): 暂无字段说明
- estimate (object): 暂无字段说明
- meta (object): 暂无字段说明
- plan_digest (string): 暂无字段说明
- results (array): 暂无字段说明
## POST /v1/agent/run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

销售排行榜需要 API Key 和数据集授权。

使用 Asklear 数据查询价目表结算。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema5": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema6": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema7": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema8": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema6"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "maxLength": 2048,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "additionalProperties": false,
      "properties": {
        "agg": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        "by": {
          "anyOf": [
            {
              "pattern": "^[a-z][a-z0-9_]{0,63}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "dataset": {
          "const": "tmall"
        },
        "month": {
          "pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
          "type": "string"
        },
        "top": {
          "default": 100,
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "dataset",
        "agg",
        "month"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "get_ranking"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "agg": "brand",
    "by": "gmv",
    "dataset": "tmall",
    "month": "2026-06",
    "top": 10
  },
  "operation": "get_ranking"
}
```

### Synthetic response / 合成响应

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

- data (array): 暂无字段说明
- meta (object): 暂无字段说明
## run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

销售排行榜需要 API Key 和数据集授权。

使用 Asklear 数据查询价目表结算。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema5": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema6": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema7": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema8": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema6"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "maxLength": 2048,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "additionalProperties": false,
      "properties": {
        "agg": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        "by": {
          "anyOf": [
            {
              "pattern": "^[a-z][a-z0-9_]{0,63}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "dataset": {
          "const": "tmall"
        },
        "month": {
          "pattern": "^\\d{4}-(0[1-9]|1[0-2])$",
          "type": "string"
        },
        "top": {
          "default": 100,
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "dataset",
        "agg",
        "month"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "get_ranking"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "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
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "agg": "brand",
    "by": "gmv",
    "dataset": "tmall",
    "month": "2026-06",
    "top": 10
  },
  "operation": "get_ranking"
}
```

### Synthetic response / 合成响应

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

- data (array): 暂无字段说明
- meta (object): 暂无字段说明
## POST /v1/agent/run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

数据样例需要 API Key，并受样例配额限制。

使用现有样例配额；数据查询费用为 0，不涉及供应商 API 采购。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema5": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema6": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema7": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema8": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema6"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "maxLength": 2048,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "additionalProperties": false,
      "properties": {
        "dataset": {
          "const": "tmall"
        },
        "n": {
          "default": 10,
          "maximum": 10,
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "dataset"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "sample_rows"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall",
    "n": 10
  },
  "operation": "sample_rows"
}
```

### Synthetic response / 合成响应

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

- data (array): 暂无字段说明
- meta (object): 暂无字段说明
## run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

数据样例需要 API Key，并受样例配额限制。

使用现有样例配额；数据查询费用为 0，不涉及供应商 API 采购。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema5": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema6": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema7": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema8": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema6"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "maxLength": 2048,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "additionalProperties": false,
      "properties": {
        "dataset": {
          "const": "tmall"
        },
        "n": {
          "default": 10,
          "maximum": 10,
          "minimum": 1,
          "type": "integer"
        }
      },
      "required": [
        "dataset"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "sample_rows"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "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
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall",
    "n": 10
  },
  "operation": "sample_rows"
}
```

### Synthetic response / 合成响应

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

- data (array): 暂无字段说明
- meta (object): 暂无字段说明
## POST /v1/agent/run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

数据范围与字段说明需要 API Key 和数据集授权。

仅读取元数据，不收取数据查询费用，也不涉及供应商 API 采购。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema5": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema6": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema7": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema8": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema6"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "maxLength": 2048,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "additionalProperties": false,
      "properties": {
        "dataset": {
          "const": "tmall"
        },
        "task": {
          "anyOf": [
            {
              "pattern": "^[a-z][a-z0-9_]*$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "dataset"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "describe"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall"
  },
  "operation": "describe"
}
```

### Synthetic response / 合成响应

```json
{
  "dataset": "tmall",
  "fields": []
}
```

- attributes (array): 暂无字段说明
- available_months (array): 暂无字段说明
- capability_version (string): 暂无字段说明
- catalog_only (boolean): 暂无字段说明
- contract_version (string): 暂无字段说明
- dataset (string): 暂无字段说明
- dataset_document (object): 暂无字段说明
- detail_fields (array): 暂无字段说明
- dimensions (array): 暂无字段说明
- display_name (string): 暂无字段说明
- document (object): 暂无字段说明
- entity_types (array): 暂无字段说明
- examples (array): 暂无字段说明
- field_contract_version (integer): 暂无字段说明
- fields (array): 暂无字段说明
- filters_allowed (array): 暂无字段说明
- known_gaps (array): 暂无字段说明
- limitations (array): 暂无字段说明
- limits (object): 暂无字段说明
- metrics (array): 暂无字段说明
- platform_methods (object): 暂无字段说明
- query_contract (object): 暂无字段说明
- recipe (object): 暂无字段说明
- recipes (array): 暂无字段说明
- release_checksum (string|null): 暂无字段说明
- release_ref (string|null): 暂无字段说明
- restatements (array): 暂无字段说明
- supported_tasks (array): 暂无字段说明
- task (string): 暂无字段说明
- time_grain (string): 暂无字段说明
- time_range (object): 暂无字段说明
- time_ranges (array): 暂无字段说明
## run

native · available · api_key

REST 需要客户 API Key；MCP 需要已开放的服务及现有授权；CLI 需要已发布且包含该命令的客户端。

数据范围与字段说明需要 API Key 和数据集授权。

仅读取元数据，不收取数据查询费用，也不涉及供应商 API 采购。

请求声明 idempotency_key 时，同一次操作复用原键；元数据 GET 只读。

等待态响应提供结果/状态引用。先读取原结果；超时或结果不明时禁止自动重新提交付费执行。401/403/422 应先修正鉴权、权限或输入。

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "include_trends": {
          "default": "true",
          "enum": [
            "true",
            "false"
          ],
          "type": "string"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "product": {
          "maxLength": 2048,
          "minLength": 10,
          "type": "string"
        },
        "since": {
          "default": "",
          "maxLength": 10,
          "type": "string"
        },
        "star": {
          "default": "all",
          "enum": [
            "all",
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "type": "string"
        },
        "verified_purchase_only": {
          "default": "false",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        }
      },
      "required": [
        "product"
      ],
      "type": "object"
    },
    "Schema3": {
      "additionalProperties": false,
      "properties": {
        "country": {
          "default": "US",
          "enum": [
            "US",
            "GB",
            "DE",
            "FR",
            "IN",
            "CA",
            "JP",
            "ES",
            "IT",
            "MX",
            "AE",
            "AU",
            "BR",
            "SA"
          ],
          "type": "string"
        },
        "page": {
          "default": 1,
          "maximum": 10000,
          "minimum": 1,
          "type": "integer"
        },
        "query": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "Schema4": {
      "additionalProperties": false,
      "properties": {
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        }
      },
      "required": [
        "platform"
      ],
      "type": "object"
    },
    "Schema5": {
      "additionalProperties": false,
      "properties": {
        "content_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_replies": {
          "default": false,
          "type": "boolean"
        },
        "max_comments": {
          "anyOf": [
            {
              "minimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema6": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "items": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "array"
        },
        {
          "additionalProperties": {
            "$ref": "#/$defs/Schema6"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "Schema7": {
      "additionalProperties": false,
      "properties": {
        "creator_ref": {
          "anyOf": [
            {
              "maxLength": 2048,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "recent_content_limit": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 4096,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    },
    "Schema8": {
      "additionalProperties": false,
      "properties": {
        "filters": {
          "anyOf": [
            {
              "additionalProperties": {
                "$ref": "#/$defs/Schema6"
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "include_details": {
          "default": false,
          "type": "boolean"
        },
        "max_items": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "pages": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "const": "max",
              "type": "string"
            }
          ],
          "default": 3
        },
        "platform": {
          "enum": [
            "xhs",
            "douyin",
            "bilibili",
            "weibo",
            "wechat",
            "wechat_channels",
            "web",
            "amazon",
            "facebook",
            "instagram",
            "jd",
            "kuaishou",
            "linkedin",
            "reddit",
            "search",
            "taobao",
            "tiktok",
            "twitter",
            "xianyu",
            "youtube",
            "zhihu"
          ],
          "type": "string"
        },
        "query": {
          "maxLength": 500,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "platform",
        "query"
      ],
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "maxLength": 2048,
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "idempotency_key": {
      "maxLength": 256,
      "minLength": 1,
      "type": "string"
    },
    "include_details": {
      "default": false,
      "type": "boolean"
    },
    "input": {
      "additionalProperties": false,
      "properties": {
        "dataset": {
          "const": "tmall"
        },
        "task": {
          "anyOf": [
            {
              "pattern": "^[a-z][a-z0-9_]*$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "dataset"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "minimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "max_detail_items": {
      "anyOf": [
        {
          "maximum": 128,
          "minimum": 1,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "operation": {
      "const": "describe"
    },
    "pages": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "const": "max",
          "type": "string"
        },
        {
          "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
    },
    "wait_seconds": {
      "default": 10,
      "maximum": 30,
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "operation",
    "input",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "dataset": "tmall"
  },
  "operation": "describe"
}
```

### Synthetic response / 合成响应

```json
{
  "dataset": "tmall",
  "fields": []
}
```

- attributes (array): 暂无字段说明
- available_months (array): 暂无字段说明
- capability_version (string): 暂无字段说明
- catalog_only (boolean): 暂无字段说明
- contract_version (string): 暂无字段说明
- dataset (string): 暂无字段说明
- dataset_document (object): 暂无字段说明
- detail_fields (array): 暂无字段说明
- dimensions (array): 暂无字段说明
- display_name (string): 暂无字段说明
- document (object): 暂无字段说明
- entity_types (array): 暂无字段说明
- examples (array): 暂无字段说明
- field_contract_version (integer): 暂无字段说明
- fields (array): 暂无字段说明
- filters_allowed (array): 暂无字段说明
- known_gaps (array): 暂无字段说明
- limitations (array): 暂无字段说明
- limits (object): 暂无字段说明
- metrics (array): 暂无字段说明
- platform_methods (object): 暂无字段说明
- query_contract (object): 暂无字段说明
- recipe (object): 暂无字段说明
- recipes (array): 暂无字段说明
- release_checksum (string|null): 暂无字段说明
- release_ref (string|null): 暂无字段说明
- restatements (array): 暂无字段说明
- supported_tasks (array): 暂无字段说明
- task (string): 暂无字段说明
- time_grain (string): 暂无字段说明
- time_range (object): 暂无字段说明
- time_ranges (array): 暂无字段说明