# 拼多多商品月度销量明细表

拼多多商品、品牌、品类和店铺的月度销售指标；访问以环境和租户状态为准。

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

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

拼多多

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

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

## GET /v1/datasets/pdd

legacy · available · api_key, oauth

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

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

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

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

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

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "pdd"
    },
    "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": "pdd"
}
```

### Synthetic response / 合成响应

```json
{
  "dimensions": [
    {
      "desc": "拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。",
      "desc_i18n": {
        "en": "Stable PDD product identifier used for exact filtering and paired with the canonical product-detail URL in public results.",
        "zh-CN": "拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_id",
      "reference_formats": [
        "pdd_product_id",
        "pdd_product_url"
      ],
      "type": "string"
    },
    {
      "desc": "拼多多源数据记录的月度商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。",
      "desc_i18n": {
        "en": "Product title recorded by the PDD source 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,
      "name": "title",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "根据 product_id 生成的标准拼多多商品详情链接，用于商品引用；在汇总中使用时需要按商品粒度分组。",
      "desc_i18n": {
        "en": "Canonical PDD product-detail URL generated from product_id; it identifies the product reference and requires product-level grouping when used in aggregates.",
        "zh-CN": "根据 product_id 生成的标准拼多多商品详情链接，用于商品引用；在汇总中使用时需要按商品粒度分组。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_url",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。",
      "desc_i18n": {
        "en": "Stable PDD shop identifier used for exact filtering and scope selection; no verified canonical shop URL is available in this release.",
        "zh-CN": "拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_id",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多源数据记录的店铺名称，名称可能随时间变化；用作筛选前应通过 search_values 对齐。",
      "desc_i18n": {
        "en": "Shop name recorded by the PDD source; names can change over time and should be resolved with search_values before use as a filter.",
        "zh-CN": "拼多多源数据记录的店铺名称，名称可能随时间变化；用作筛选前应通过 search_values 对齐。"
      },
      "dictionary_searchable": true,
      "entity_type": "shop",
      "name": "shop",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多源数据记录的品牌名称，可能为空或存在写法差异；作为筛选条件前应先对齐名称。",
      "desc_i18n": {
        "en": "Brand name recorded by the PDD source; values may be empty or vary in spelling, so resolve names before treating them as a filter.",
        "zh-CN": "拼多多源数据记录的品牌名称，可能为空或存在写法差异；作为筛选条件前应先对齐名称。"
      },
      "dictionary_searchable": true,
      "name": "brand",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多标准类目体系中的一级类目名称；这是上游开放值，可能为空。",
      "desc_i18n": {
        "en": "Level-1 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.",
        "zh-CN": "拼多多标准类目体系中的一级类目名称；这是上游开放值，可能为空。"
      },
      "dictionary_searchable": true,
      "name": "category_l1",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多标准类目体系中的二级类目名称；这是上游开放值，可能为空。",
      "desc_i18n": {
        "en": "Level-2 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.",
        "zh-CN": "拼多多标准类目体系中的二级类目名称；这是上游开放值，可能为空。"
      },
      "dictionary_searchable": true,
      "name": "category_l2",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多标准类目体系中的三级类目名称；这是上游开放值，可能为空。",
      "desc_i18n": {
        "en": "Level-3 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.",
        "zh-CN": "拼多多标准类目体系中的三级类目名称；这是上游开放值，可能为空。"
      },
      "dictionary_searchable": true,
      "name": "category_l3",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。",
      "desc_i18n": {
        "en": "Calendar month to which the PDD product sales record belongs, formatted as YYYY-MM; the public dataset grain is monthly.",
        "zh-CN": "拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。"
      },
      "dictionary_searchable": false,
      "name": "month",
      "reference_formats": [],
      "type": "time"
    },
    {
      "desc": "标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。",
      "desc_i18n": {
        "en": "Flag indicating whether the record is associated with PDD's billion-subsidy program; upstream values remain open and are not a closed enum.",
        "zh-CN": "标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。"
      },
      "dictionary_searchable": true,
      "name": "billion_subsidy_tag",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多上游提供的原始一级类目值，用于类目对照，不应假定它与标准类目一致。",
      "desc_i18n": {
        "en": "Original level-1 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.",
        "zh-CN": "拼多多上游提供的原始一级类目值，用于类目对照，不应假定它与标准类目一致。"
      },
      "dictionary_searchable": true,
      "name": "ori_category_l1",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多上游提供的原始二级类目值，用于类目对照，不应假定它与标准类目一致。",
      "desc_i18n": {
        "en": "Original level-2 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.",
        "zh-CN": "拼多多上游提供的原始二级类目值，用于类目对照，不应假定它与标准类目一致。"
      },
      "dictionary_searchable": true,
      "name": "ori_category_l2",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多上游提供的原始三级类目值，用于类目对照，不应假定它与标准类目一致。",
      "desc_i18n": {
        "en": "Original level-3 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.",
        "zh-CN": "拼多多上游提供的原始三级类目值，用于类目对照，不应假定它与标准类目一致。"
      },
      "dictionary_searchable": true,
      "name": "ori_category_l3",
      "reference_formats": [],
      "type": "string"
    }
  ],
  "metrics": [
    {
      "certified": true,
      "desc": "补贴后商品交易总额，按 SUM(discount_sales) 计算；是本 PDD 版本用于比较的主要销售额口径。",
      "desc_i18n": {
        "en": "Post-subsidy gross merchandise value calculated as SUM(discount_sales); it is the primary comparable sales amount for this PDD release.",
        "zh-CN": "补贴后商品交易总额，按 SUM(discount_sales) 计算；是本 PDD 版本用于比较的主要销售额口径。"
      },
      "name": "gmv"
    },
    {
      "certified": true,
      "desc": "月销量按 SUM(count) 计算，其中 count 来自上游月度 volume，不是累计 total_volume。",
      "desc_i18n": {
        "en": "Monthly units sold calculated as SUM(count), where count comes from the upstream monthly volume rather than cumulative total_volume.",
        "zh-CN": "月销量按 SUM(count) 计算，其中 count 来自上游月度 volume，不是累计 total_volume。"
      },
      "name": "units"
    },
    {
      "certified": true,
      "desc": "补贴后加权平均成交价，按 SUM(discount_sales) 除以 SUM(count) 计算，并对销量为零做保护。",
      "desc_i18n": {
        "en": "Weighted average post-subsidy selling price calculated from SUM(discount_sales) divided by SUM(count), with zero-count protection.",
        "zh-CN": "补贴后加权平均成交价，按 SUM(discount_sales) 除以 SUM(count) 计算，并对销量为零做保护。"
      },
      "name": "asp"
    }
  ]
}
```

- dimensions (array<object>): 暂无字段说明
- metrics (array<object>): 暂无字段说明
## describe

legacy · available · api_key, oauth

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

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

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

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

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

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "pdd"
    },
    "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": "pdd"
}
```

### Synthetic response / 合成响应

```json
{
  "dimensions": [
    {
      "desc": "拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。",
      "desc_i18n": {
        "en": "Stable PDD product identifier used for exact filtering and paired with the canonical product-detail URL in public results.",
        "zh-CN": "拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_id",
      "reference_formats": [
        "pdd_product_id",
        "pdd_product_url"
      ],
      "type": "string"
    },
    {
      "desc": "拼多多源数据记录的月度商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。",
      "desc_i18n": {
        "en": "Product title recorded by the PDD source 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,
      "name": "title",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "根据 product_id 生成的标准拼多多商品详情链接，用于商品引用；在汇总中使用时需要按商品粒度分组。",
      "desc_i18n": {
        "en": "Canonical PDD product-detail URL generated from product_id; it identifies the product reference and requires product-level grouping when used in aggregates.",
        "zh-CN": "根据 product_id 生成的标准拼多多商品详情链接，用于商品引用；在汇总中使用时需要按商品粒度分组。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_url",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。",
      "desc_i18n": {
        "en": "Stable PDD shop identifier used for exact filtering and scope selection; no verified canonical shop URL is available in this release.",
        "zh-CN": "拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_id",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多源数据记录的店铺名称，名称可能随时间变化；用作筛选前应通过 search_values 对齐。",
      "desc_i18n": {
        "en": "Shop name recorded by the PDD source; names can change over time and should be resolved with search_values before use as a filter.",
        "zh-CN": "拼多多源数据记录的店铺名称，名称可能随时间变化；用作筛选前应通过 search_values 对齐。"
      },
      "dictionary_searchable": true,
      "entity_type": "shop",
      "name": "shop",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多源数据记录的品牌名称，可能为空或存在写法差异；作为筛选条件前应先对齐名称。",
      "desc_i18n": {
        "en": "Brand name recorded by the PDD source; values may be empty or vary in spelling, so resolve names before treating them as a filter.",
        "zh-CN": "拼多多源数据记录的品牌名称，可能为空或存在写法差异；作为筛选条件前应先对齐名称。"
      },
      "dictionary_searchable": true,
      "name": "brand",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多标准类目体系中的一级类目名称；这是上游开放值，可能为空。",
      "desc_i18n": {
        "en": "Level-1 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.",
        "zh-CN": "拼多多标准类目体系中的一级类目名称；这是上游开放值，可能为空。"
      },
      "dictionary_searchable": true,
      "name": "category_l1",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多标准类目体系中的二级类目名称；这是上游开放值，可能为空。",
      "desc_i18n": {
        "en": "Level-2 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.",
        "zh-CN": "拼多多标准类目体系中的二级类目名称；这是上游开放值，可能为空。"
      },
      "dictionary_searchable": true,
      "name": "category_l2",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多标准类目体系中的三级类目名称；这是上游开放值，可能为空。",
      "desc_i18n": {
        "en": "Level-3 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.",
        "zh-CN": "拼多多标准类目体系中的三级类目名称；这是上游开放值，可能为空。"
      },
      "dictionary_searchable": true,
      "name": "category_l3",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。",
      "desc_i18n": {
        "en": "Calendar month to which the PDD product sales record belongs, formatted as YYYY-MM; the public dataset grain is monthly.",
        "zh-CN": "拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。"
      },
      "dictionary_searchable": false,
      "name": "month",
      "reference_formats": [],
      "type": "time"
    },
    {
      "desc": "标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。",
      "desc_i18n": {
        "en": "Flag indicating whether the record is associated with PDD's billion-subsidy program; upstream values remain open and are not a closed enum.",
        "zh-CN": "标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。"
      },
      "dictionary_searchable": true,
      "name": "billion_subsidy_tag",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多上游提供的原始一级类目值，用于类目对照，不应假定它与标准类目一致。",
      "desc_i18n": {
        "en": "Original level-1 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.",
        "zh-CN": "拼多多上游提供的原始一级类目值，用于类目对照，不应假定它与标准类目一致。"
      },
      "dictionary_searchable": true,
      "name": "ori_category_l1",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多上游提供的原始二级类目值，用于类目对照，不应假定它与标准类目一致。",
      "desc_i18n": {
        "en": "Original level-2 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.",
        "zh-CN": "拼多多上游提供的原始二级类目值，用于类目对照，不应假定它与标准类目一致。"
      },
      "dictionary_searchable": true,
      "name": "ori_category_l2",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多上游提供的原始三级类目值，用于类目对照，不应假定它与标准类目一致。",
      "desc_i18n": {
        "en": "Original level-3 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.",
        "zh-CN": "拼多多上游提供的原始三级类目值，用于类目对照，不应假定它与标准类目一致。"
      },
      "dictionary_searchable": true,
      "name": "ori_category_l3",
      "reference_formats": [],
      "type": "string"
    }
  ],
  "metrics": [
    {
      "certified": true,
      "desc": "补贴后商品交易总额，按 SUM(discount_sales) 计算；是本 PDD 版本用于比较的主要销售额口径。",
      "desc_i18n": {
        "en": "Post-subsidy gross merchandise value calculated as SUM(discount_sales); it is the primary comparable sales amount for this PDD release.",
        "zh-CN": "补贴后商品交易总额，按 SUM(discount_sales) 计算；是本 PDD 版本用于比较的主要销售额口径。"
      },
      "name": "gmv"
    },
    {
      "certified": true,
      "desc": "月销量按 SUM(count) 计算，其中 count 来自上游月度 volume，不是累计 total_volume。",
      "desc_i18n": {
        "en": "Monthly units sold calculated as SUM(count), where count comes from the upstream monthly volume rather than cumulative total_volume.",
        "zh-CN": "月销量按 SUM(count) 计算，其中 count 来自上游月度 volume，不是累计 total_volume。"
      },
      "name": "units"
    },
    {
      "certified": true,
      "desc": "补贴后加权平均成交价，按 SUM(discount_sales) 除以 SUM(count) 计算，并对销量为零做保护。",
      "desc_i18n": {
        "en": "Weighted average post-subsidy selling price calculated from SUM(discount_sales) divided by SUM(count), with zero-count protection.",
        "zh-CN": "补贴后加权平均成交价，按 SUM(discount_sales) 除以 SUM(count) 计算，并对销量为零做保护。"
      },
      "name": "asp"
    }
  ]
}
```

- dimensions (array<object>): 暂无字段说明
- metrics (array<object>): 暂无字段说明
## asklear describe

legacy · available · api_key, oauth

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

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

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

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

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

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "pdd"
    },
    "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": "pdd"
}
```

### Synthetic response / 合成响应

```json
{
  "dimensions": [
    {
      "desc": "拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。",
      "desc_i18n": {
        "en": "Stable PDD product identifier used for exact filtering and paired with the canonical product-detail URL in public results.",
        "zh-CN": "拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_id",
      "reference_formats": [
        "pdd_product_id",
        "pdd_product_url"
      ],
      "type": "string"
    },
    {
      "desc": "拼多多源数据记录的月度商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。",
      "desc_i18n": {
        "en": "Product title recorded by the PDD source 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,
      "name": "title",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "根据 product_id 生成的标准拼多多商品详情链接，用于商品引用；在汇总中使用时需要按商品粒度分组。",
      "desc_i18n": {
        "en": "Canonical PDD product-detail URL generated from product_id; it identifies the product reference and requires product-level grouping when used in aggregates.",
        "zh-CN": "根据 product_id 生成的标准拼多多商品详情链接，用于商品引用；在汇总中使用时需要按商品粒度分组。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_url",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。",
      "desc_i18n": {
        "en": "Stable PDD shop identifier used for exact filtering and scope selection; no verified canonical shop URL is available in this release.",
        "zh-CN": "拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_id",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多源数据记录的店铺名称，名称可能随时间变化；用作筛选前应通过 search_values 对齐。",
      "desc_i18n": {
        "en": "Shop name recorded by the PDD source; names can change over time and should be resolved with search_values before use as a filter.",
        "zh-CN": "拼多多源数据记录的店铺名称，名称可能随时间变化；用作筛选前应通过 search_values 对齐。"
      },
      "dictionary_searchable": true,
      "entity_type": "shop",
      "name": "shop",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多源数据记录的品牌名称，可能为空或存在写法差异；作为筛选条件前应先对齐名称。",
      "desc_i18n": {
        "en": "Brand name recorded by the PDD source; values may be empty or vary in spelling, so resolve names before treating them as a filter.",
        "zh-CN": "拼多多源数据记录的品牌名称，可能为空或存在写法差异；作为筛选条件前应先对齐名称。"
      },
      "dictionary_searchable": true,
      "name": "brand",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多标准类目体系中的一级类目名称；这是上游开放值，可能为空。",
      "desc_i18n": {
        "en": "Level-1 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.",
        "zh-CN": "拼多多标准类目体系中的一级类目名称；这是上游开放值，可能为空。"
      },
      "dictionary_searchable": true,
      "name": "category_l1",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多标准类目体系中的二级类目名称；这是上游开放值，可能为空。",
      "desc_i18n": {
        "en": "Level-2 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.",
        "zh-CN": "拼多多标准类目体系中的二级类目名称；这是上游开放值，可能为空。"
      },
      "dictionary_searchable": true,
      "name": "category_l2",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多标准类目体系中的三级类目名称；这是上游开放值，可能为空。",
      "desc_i18n": {
        "en": "Level-3 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.",
        "zh-CN": "拼多多标准类目体系中的三级类目名称；这是上游开放值，可能为空。"
      },
      "dictionary_searchable": true,
      "name": "category_l3",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。",
      "desc_i18n": {
        "en": "Calendar month to which the PDD product sales record belongs, formatted as YYYY-MM; the public dataset grain is monthly.",
        "zh-CN": "拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。"
      },
      "dictionary_searchable": false,
      "name": "month",
      "reference_formats": [],
      "type": "time"
    },
    {
      "desc": "标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。",
      "desc_i18n": {
        "en": "Flag indicating whether the record is associated with PDD's billion-subsidy program; upstream values remain open and are not a closed enum.",
        "zh-CN": "标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。"
      },
      "dictionary_searchable": true,
      "name": "billion_subsidy_tag",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多上游提供的原始一级类目值，用于类目对照，不应假定它与标准类目一致。",
      "desc_i18n": {
        "en": "Original level-1 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.",
        "zh-CN": "拼多多上游提供的原始一级类目值，用于类目对照，不应假定它与标准类目一致。"
      },
      "dictionary_searchable": true,
      "name": "ori_category_l1",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多上游提供的原始二级类目值，用于类目对照，不应假定它与标准类目一致。",
      "desc_i18n": {
        "en": "Original level-2 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.",
        "zh-CN": "拼多多上游提供的原始二级类目值，用于类目对照，不应假定它与标准类目一致。"
      },
      "dictionary_searchable": true,
      "name": "ori_category_l2",
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "拼多多上游提供的原始三级类目值，用于类目对照，不应假定它与标准类目一致。",
      "desc_i18n": {
        "en": "Original level-3 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.",
        "zh-CN": "拼多多上游提供的原始三级类目值，用于类目对照，不应假定它与标准类目一致。"
      },
      "dictionary_searchable": true,
      "name": "ori_category_l3",
      "reference_formats": [],
      "type": "string"
    }
  ],
  "metrics": [
    {
      "certified": true,
      "desc": "补贴后商品交易总额，按 SUM(discount_sales) 计算；是本 PDD 版本用于比较的主要销售额口径。",
      "desc_i18n": {
        "en": "Post-subsidy gross merchandise value calculated as SUM(discount_sales); it is the primary comparable sales amount for this PDD release.",
        "zh-CN": "补贴后商品交易总额，按 SUM(discount_sales) 计算；是本 PDD 版本用于比较的主要销售额口径。"
      },
      "name": "gmv"
    },
    {
      "certified": true,
      "desc": "月销量按 SUM(count) 计算，其中 count 来自上游月度 volume，不是累计 total_volume。",
      "desc_i18n": {
        "en": "Monthly units sold calculated as SUM(count), where count comes from the upstream monthly volume rather than cumulative total_volume.",
        "zh-CN": "月销量按 SUM(count) 计算，其中 count 来自上游月度 volume，不是累计 total_volume。"
      },
      "name": "units"
    },
    {
      "certified": true,
      "desc": "补贴后加权平均成交价，按 SUM(discount_sales) 除以 SUM(count) 计算，并对销量为零做保护。",
      "desc_i18n": {
        "en": "Weighted average post-subsidy selling price calculated from SUM(discount_sales) divided by SUM(count), with zero-count protection.",
        "zh-CN": "补贴后加权平均成交价，按 SUM(discount_sales) 除以 SUM(count) 计算，并对销量为零做保护。"
      },
      "name": "asp"
    }
  ]
}
```

- dimensions (array<object>): 暂无字段说明
- metrics (array<object>): 暂无字段说明
## GET /v1/datasets/pdd/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": "pdd"
    },
    "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": "pdd",
  "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": "pdd"
    },
    "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": "pdd",
  "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": "pdd"
    },
    "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": "pdd",
  "n": 10
}
```

### Synthetic response / 合成响应

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

- data (array<object>): 暂无字段说明
## POST /v1/query_metrics

legacy · available · api_key, oauth

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

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

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

请求声明 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": "pdd"
    },
    "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",
          "brand",
          "category_l1",
          "category_l2",
          "category_l3",
          "month",
          "billion_subsidy_tag",
          "ori_category_l1",
          "ori_category_l2",
          "ori_category_l3"
        ]
      },
      "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": "pdd",
  "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": "pdd"
  }
}
```

- data[].product_id (string): 拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。
- data[].title (string): 拼多多源数据记录的月度商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].product_url (string): 根据 product_id 生成的标准拼多多商品详情链接，用于商品引用；在汇总中使用时需要按商品粒度分组。
- data[].shop_id (string): 拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。
- data[].shop (string): 拼多多源数据记录的店铺名称，名称可能随时间变化；用作筛选前应通过 search_values 对齐。
- data[].brand (string): 拼多多源数据记录的品牌名称，可能为空或存在写法差异；作为筛选条件前应先对齐名称。
- data[].category_l1 (string): 拼多多标准类目体系中的一级类目名称；这是上游开放值，可能为空。
- data[].category_l2 (string): 拼多多标准类目体系中的二级类目名称；这是上游开放值，可能为空。
- data[].category_l3 (string): 拼多多标准类目体系中的三级类目名称；这是上游开放值，可能为空。
- data[].month (time): 拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。
- data[].billion_subsidy_tag (string): 标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。
- data[].ori_category_l1 (string): 拼多多上游提供的原始一级类目值，用于类目对照，不应假定它与标准类目一致。
- data[].ori_category_l2 (string): 拼多多上游提供的原始二级类目值，用于类目对照，不应假定它与标准类目一致。
- data[].ori_category_l3 (string): 拼多多上游提供的原始三级类目值，用于类目对照，不应假定它与标准类目一致。
- data[].gmv (number): 补贴后商品交易总额，按 SUM(discount_sales) 计算；是本 PDD 版本用于比较的主要销售额口径。
- data[].units (number): 月销量按 SUM(count) 计算，其中 count 来自上游月度 volume，不是累计 total_volume。
- data[].asp (number): 补贴后加权平均成交价，按 SUM(discount_sales) 除以 SUM(count) 计算，并对销量为零做保护。
## query_metrics

legacy · available · api_key, oauth

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

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

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

请求声明 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": "pdd"
    },
    "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",
          "brand",
          "category_l1",
          "category_l2",
          "category_l3",
          "month",
          "billion_subsidy_tag",
          "ori_category_l1",
          "ori_category_l2",
          "ori_category_l3"
        ]
      },
      "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": "pdd",
  "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": "pdd"
  }
}
```

- data[].product_id (string): 拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。
- data[].title (string): 拼多多源数据记录的月度商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].product_url (string): 根据 product_id 生成的标准拼多多商品详情链接，用于商品引用；在汇总中使用时需要按商品粒度分组。
- data[].shop_id (string): 拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。
- data[].shop (string): 拼多多源数据记录的店铺名称，名称可能随时间变化；用作筛选前应通过 search_values 对齐。
- data[].brand (string): 拼多多源数据记录的品牌名称，可能为空或存在写法差异；作为筛选条件前应先对齐名称。
- data[].category_l1 (string): 拼多多标准类目体系中的一级类目名称；这是上游开放值，可能为空。
- data[].category_l2 (string): 拼多多标准类目体系中的二级类目名称；这是上游开放值，可能为空。
- data[].category_l3 (string): 拼多多标准类目体系中的三级类目名称；这是上游开放值，可能为空。
- data[].month (time): 拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。
- data[].billion_subsidy_tag (string): 标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。
- data[].ori_category_l1 (string): 拼多多上游提供的原始一级类目值，用于类目对照，不应假定它与标准类目一致。
- data[].ori_category_l2 (string): 拼多多上游提供的原始二级类目值，用于类目对照，不应假定它与标准类目一致。
- data[].ori_category_l3 (string): 拼多多上游提供的原始三级类目值，用于类目对照，不应假定它与标准类目一致。
- data[].gmv (number): 补贴后商品交易总额，按 SUM(discount_sales) 计算；是本 PDD 版本用于比较的主要销售额口径。
- data[].units (number): 月销量按 SUM(count) 计算，其中 count 来自上游月度 volume，不是累计 total_volume。
- data[].asp (number): 补贴后加权平均成交价，按 SUM(discount_sales) 除以 SUM(count) 计算，并对销量为零做保护。
## asklear query

legacy · available · api_key, oauth

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

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

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

请求声明 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": "pdd"
    },
    "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",
          "brand",
          "category_l1",
          "category_l2",
          "category_l3",
          "month",
          "billion_subsidy_tag",
          "ori_category_l1",
          "ori_category_l2",
          "ori_category_l3"
        ]
      },
      "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": "pdd",
  "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": "pdd"
  }
}
```

- data[].product_id (string): 拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。
- data[].title (string): 拼多多源数据记录的月度商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].product_url (string): 根据 product_id 生成的标准拼多多商品详情链接，用于商品引用；在汇总中使用时需要按商品粒度分组。
- data[].shop_id (string): 拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。
- data[].shop (string): 拼多多源数据记录的店铺名称，名称可能随时间变化；用作筛选前应通过 search_values 对齐。
- data[].brand (string): 拼多多源数据记录的品牌名称，可能为空或存在写法差异；作为筛选条件前应先对齐名称。
- data[].category_l1 (string): 拼多多标准类目体系中的一级类目名称；这是上游开放值，可能为空。
- data[].category_l2 (string): 拼多多标准类目体系中的二级类目名称；这是上游开放值，可能为空。
- data[].category_l3 (string): 拼多多标准类目体系中的三级类目名称；这是上游开放值，可能为空。
- data[].month (time): 拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。
- data[].billion_subsidy_tag (string): 标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。
- data[].ori_category_l1 (string): 拼多多上游提供的原始一级类目值，用于类目对照，不应假定它与标准类目一致。
- data[].ori_category_l2 (string): 拼多多上游提供的原始二级类目值，用于类目对照，不应假定它与标准类目一致。
- data[].ori_category_l3 (string): 拼多多上游提供的原始三级类目值，用于类目对照，不应假定它与标准类目一致。
- data[].gmv (number): 补贴后商品交易总额，按 SUM(discount_sales) 计算；是本 PDD 版本用于比较的主要销售额口径。
- data[].units (number): 月销量按 SUM(count) 计算，其中 count 来自上游月度 volume，不是累计 total_volume。
- data[].asp (number): 补贴后加权平均成交价，按 SUM(discount_sales) 除以 SUM(count) 计算，并对销量为零做保护。
## 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": "pdd"
    },
    "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": "pdd",
  "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 需要已发布且包含该命令的客户端。

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

执行遵循现有计价；读取公开说明不扣 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": "pdd"
    },
    "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": "pdd",
  "field": "shop",
  "kw": "example",
  "limit": 10
}
```

### Synthetic response / 合成响应

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

- data (array<object>): 暂无字段说明
## search_values

legacy · available · api_key, oauth

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

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

执行遵循现有计价；读取公开说明不扣 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": "pdd"
    },
    "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": "pdd",
  "field": "shop",
  "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 需要已发布且包含该命令的客户端。

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

执行遵循现有计价；读取公开说明不扣 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": "pdd"
    },
    "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": "pdd",
  "field": "shop",
  "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 需要已发布且包含该命令的客户端。

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

执行遵循现有计价；读取公开说明不扣 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": "pdd"
    },
    "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",
          "shop_id",
          "month",
          "billion_subsidy_tag",
          "platform",
          "price",
          "count",
          "sales",
          "brand_name",
          "shop_name",
          "tech_date",
          "category_1",
          "category_2",
          "category_3",
          "total_volume",
          "total_comment_count",
          "estimate_flag",
          "discount_sales",
          "ori_category_1",
          "ori_category_2",
          "ori_category_3",
          "product_intro"
        ]
      },
      "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": "pdd",
  "fields": [
    "product_id",
    "title",
    "shop_id"
  ],
  "filters": [
    {
      "field": "product_id",
      "op": "eq",
      "value": "1234567890"
    }
  ],
  "limit": 10,
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

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

- data[].product_id (string): 拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。
- data[].title (string): 拼多多源数据记录的月度商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].shop_id (string): 拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。
- data[].month (time): 拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。
- data[].billion_subsidy_tag (string): 标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。
- data[].platform (string): 标识这些记录属于拼多多数据的平台常量，由规范导入投影补充，并非上游业务字段。
- data[].price (number): 拼多多源数据报告的商品挂牌价格，是行级数值明细字段，不是月度销售指标。
- data[].count (number): 来自上游 volume 字段的月度增量销量；不要将其解释为历史累计 total_volume。
- data[].sales (number): 由上游 value 字段提供的挂牌价销售额，与补贴后销售额并列保留以便透明比较。
- data[].brand_name (string): 拼多多源数据中的原始品牌名称列，规范 brand 字段由此投影而来，且该值可能为空。
- data[].shop_name (string): 拼多多源数据中的原始店铺名称列，规范 shop 字段由此投影而来，名称可能变化。
- data[].tech_date (string): 保留用于明细核查的上游技术日期样式字段；它不是销售月份，不得用于时间分析。
- data[].category_1 (string): 拼多多源数据中的原始一级类目名称列，在公开语义契约中改名为 category_l1。
- data[].category_2 (string): 拼多多源数据中的原始二级类目名称列，在公开语义契约中改名为 category_l2。
- data[].category_3 (string): 拼多多源数据中的原始三级类目名称列，在公开语义契约中改名为 category_l3。
- data[].total_volume (number): 拼多多源数据报告的历史累计销量，保留用于明细输出，不得当作月销量使用。
- data[].total_comment_count (number): 拼多多源数据报告的历史累计评价数，是明细字段，不是月度评价增量。
- data[].estimate_flag (string): 上游用于标记数值可能为估算值的字段，在明细中披露，但本版本不开放为筛选维度。
- data[].discount_sales (number): 拼多多源数据提供的补贴后销售额，是公开 gmv 指标使用的物理输入字段。
- data[].ori_category_1 (string): 保留用于明细输出和类目对照分析的上游原始一级类目值，与 category_1 不同。
- data[].ori_category_2 (string): 保留用于明细输出和类目对照分析的上游原始二级类目值，与 category_2 不同。
- data[].ori_category_3 (string): 保留用于明细输出和类目对照分析的上游原始三级类目值，与 category_3 不同。
- data[].product_intro (string): 拼多多源数据提供的商品简介文本，保留用于明细输出，但不作为结构化商品规格。
## query_details

legacy · available · api_key, oauth

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

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

执行遵循现有计价；读取公开说明不扣 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": "pdd"
    },
    "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",
          "shop_id",
          "month",
          "billion_subsidy_tag",
          "platform",
          "price",
          "count",
          "sales",
          "brand_name",
          "shop_name",
          "tech_date",
          "category_1",
          "category_2",
          "category_3",
          "total_volume",
          "total_comment_count",
          "estimate_flag",
          "discount_sales",
          "ori_category_1",
          "ori_category_2",
          "ori_category_3",
          "product_intro"
        ]
      },
      "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": "pdd",
  "fields": [
    "product_id",
    "title",
    "shop_id"
  ],
  "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): 拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。
- data[].title (string): 拼多多源数据记录的月度商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].shop_id (string): 拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。
- data[].month (time): 拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。
- data[].billion_subsidy_tag (string): 标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。
- data[].platform (string): 标识这些记录属于拼多多数据的平台常量，由规范导入投影补充，并非上游业务字段。
- data[].price (number): 拼多多源数据报告的商品挂牌价格，是行级数值明细字段，不是月度销售指标。
- data[].count (number): 来自上游 volume 字段的月度增量销量；不要将其解释为历史累计 total_volume。
- data[].sales (number): 由上游 value 字段提供的挂牌价销售额，与补贴后销售额并列保留以便透明比较。
- data[].brand_name (string): 拼多多源数据中的原始品牌名称列，规范 brand 字段由此投影而来，且该值可能为空。
- data[].shop_name (string): 拼多多源数据中的原始店铺名称列，规范 shop 字段由此投影而来，名称可能变化。
- data[].tech_date (string): 保留用于明细核查的上游技术日期样式字段；它不是销售月份，不得用于时间分析。
- data[].category_1 (string): 拼多多源数据中的原始一级类目名称列，在公开语义契约中改名为 category_l1。
- data[].category_2 (string): 拼多多源数据中的原始二级类目名称列，在公开语义契约中改名为 category_l2。
- data[].category_3 (string): 拼多多源数据中的原始三级类目名称列，在公开语义契约中改名为 category_l3。
- data[].total_volume (number): 拼多多源数据报告的历史累计销量，保留用于明细输出，不得当作月销量使用。
- data[].total_comment_count (number): 拼多多源数据报告的历史累计评价数，是明细字段，不是月度评价增量。
- data[].estimate_flag (string): 上游用于标记数值可能为估算值的字段，在明细中披露，但本版本不开放为筛选维度。
- data[].discount_sales (number): 拼多多源数据提供的补贴后销售额，是公开 gmv 指标使用的物理输入字段。
- data[].ori_category_1 (string): 保留用于明细输出和类目对照分析的上游原始一级类目值，与 category_1 不同。
- data[].ori_category_2 (string): 保留用于明细输出和类目对照分析的上游原始二级类目值，与 category_2 不同。
- data[].ori_category_3 (string): 保留用于明细输出和类目对照分析的上游原始三级类目值，与 category_3 不同。
- data[].product_intro (string): 拼多多源数据提供的商品简介文本，保留用于明细输出，但不作为结构化商品规格。
## asklear query-details

legacy · available · api_key, oauth

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

仅支持月粒度数据
search_products 可按商品名称或标题查找候选商品身份；query_metrics 和 query_details 的商品筛选仍需精确 product_id 或标准 mobile.yangkeduo.com 商品链接
店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名;上游未提供店铺链接
gmv 为补贴后销售额(上游 value_after_subsidy);挂牌价销售额保留在明细字段 sales 中,两者仅对百亿补贴商品不同
约 7.3% 的行由上游标记为估算值(明细字段 estimate_flag),已计入指标;该字段本版不开放为筛选维度
明细字段 total_volume 与 total_comment_count 是历史累计值,不是当月值,不可与 units 混用
明细字段 tech_date 是上游技术字段,不是销售日期,不可用于时间分析
brand_name 空值比例较高(2026-06 约 85%),品牌榜单会剔除空值
不提供评价、流量、库存、因果解释或其他平台数据
同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

执行遵循现有计价；读取公开说明不扣 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": "pdd"
    },
    "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",
          "shop_id",
          "month",
          "billion_subsidy_tag",
          "platform",
          "price",
          "count",
          "sales",
          "brand_name",
          "shop_name",
          "tech_date",
          "category_1",
          "category_2",
          "category_3",
          "total_volume",
          "total_comment_count",
          "estimate_flag",
          "discount_sales",
          "ori_category_1",
          "ori_category_2",
          "ori_category_3",
          "product_intro"
        ]
      },
      "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": "pdd",
  "fields": [
    "product_id",
    "title",
    "shop_id"
  ],
  "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): 拼多多商品的稳定标识，用于精确筛选，并在公开结果中与标准商品详情链接配套。
- data[].title (string): 拼多多源数据记录的月度商品标题；可用于结果展示和分组，但不能直接作为 query_metrics 或 query_details 的筛选条件。按名称或标题查找商品请使用 search_products。
- data[].shop_id (string): 拼多多店铺的稳定标识，用于精确筛选和范围选择；本版本没有已验证的标准店铺链接。
- data[].month (time): 拼多多商品销售记录所属自然月，格式为 YYYY-MM；公开数据集按月粒度提供。
- data[].billion_subsidy_tag (string): 标记记录是否关联拼多多百亿补贴计划；上游取值保持开放，不声明为固定枚举。
- data[].platform (string): 标识这些记录属于拼多多数据的平台常量，由规范导入投影补充，并非上游业务字段。
- data[].price (number): 拼多多源数据报告的商品挂牌价格，是行级数值明细字段，不是月度销售指标。
- data[].count (number): 来自上游 volume 字段的月度增量销量；不要将其解释为历史累计 total_volume。
- data[].sales (number): 由上游 value 字段提供的挂牌价销售额，与补贴后销售额并列保留以便透明比较。
- data[].brand_name (string): 拼多多源数据中的原始品牌名称列，规范 brand 字段由此投影而来，且该值可能为空。
- data[].shop_name (string): 拼多多源数据中的原始店铺名称列，规范 shop 字段由此投影而来，名称可能变化。
- data[].tech_date (string): 保留用于明细核查的上游技术日期样式字段；它不是销售月份，不得用于时间分析。
- data[].category_1 (string): 拼多多源数据中的原始一级类目名称列，在公开语义契约中改名为 category_l1。
- data[].category_2 (string): 拼多多源数据中的原始二级类目名称列，在公开语义契约中改名为 category_l2。
- data[].category_3 (string): 拼多多源数据中的原始三级类目名称列，在公开语义契约中改名为 category_l3。
- data[].total_volume (number): 拼多多源数据报告的历史累计销量，保留用于明细输出，不得当作月销量使用。
- data[].total_comment_count (number): 拼多多源数据报告的历史累计评价数，是明细字段，不是月度评价增量。
- data[].estimate_flag (string): 上游用于标记数值可能为估算值的字段，在明细中披露，但本版本不开放为筛选维度。
- data[].discount_sales (number): 拼多多源数据提供的补贴后销售额，是公开 gmv 指标使用的物理输入字段。
- data[].ori_category_1 (string): 保留用于明细输出和类目对照分析的上游原始一级类目值，与 category_1 不同。
- data[].ori_category_2 (string): 保留用于明细输出和类目对照分析的上游原始二级类目值，与 category_2 不同。
- data[].ori_category_3 (string): 保留用于明细输出和类目对照分析的上游原始三级类目值，与 category_3 不同。
- data[].product_intro (string): 拼多多源数据提供的商品简介文本，保留用于明细输出，但不作为结构化商品规格。
## 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": "pdd"
    },
    "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": "pdd",
  "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": "pdd"
        },
        "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": "pdd",
    "group_by": [
      "brand"
    ],
    "limit": 10,
    "metrics": [
      "gmv"
    ],
    "time": {
      "last_complete_months": 1
    }
  },
  "operation": "query_metrics"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "group_by": [
      "brand"
    ],
    "limit": 10,
    "metrics": [
      "gmv"
    ],
    "time": {
      "last_complete_months": 1
    }
  },
  "operation": "query_metrics"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "fields": [
      "product_id"
    ],
    "limit": 10,
    "time": {
      "last_complete_months": 1
    }
  },
  "operation": "query_details"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "fields": [
      "product_id"
    ],
    "limit": 10,
    "time": {
      "last_complete_months": 1
    }
  },
  "operation": "query_details"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "field": "brand",
    "kw": null,
    "limit": 20
  },
  "operation": "search_values"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "field": "brand",
    "kw": null,
    "limit": 20
  },
  "operation": "search_values"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "limit": 10,
    "query": "sample"
  },
  "operation": "search_products"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "limit": 10,
    "query": "sample"
  },
  "operation": "search_products"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "month": "2026-06",
    "top": 10
  },
  "operation": "get_ranking"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "month": "2026-06",
    "top": 10
  },
  "operation": "get_ranking"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "n": 10
  },
  "operation": "sample_rows"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd",
    "n": 10
  },
  "operation": "sample_rows"
}
```

### Synthetic response / 合成响应

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

- 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": "pdd"
        },
        "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": "pdd"
  },
  "operation": "describe"
}
```

### Synthetic response / 合成响应

```json
{
  "dataset": "pdd",
  "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": "pdd"
        },
        "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": "pdd"
  },
  "operation": "describe"
}
```

### Synthetic response / 合成响应

```json
{
  "dataset": "pdd",
  "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): 暂无字段说明