# PDD Monthly Product Sales

Monthly PDD sales metrics for products, brands, categories, and shops; access is environment and tenant scoped.

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

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

PDD

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

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

## GET /v1/datasets/pdd

legacy · available · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "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>): No field description available
- metrics (array<object>): No field description available
## describe

legacy · available · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "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>): No field description available
- metrics (array<object>): No field description available
## asklear describe

legacy · unavailable · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "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>): No field description available
- metrics (array<object>): No field description available
## GET /v1/datasets/pdd/sample

legacy · available · api_key, oauth

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

Example row shape only; samples are not analytical evidence.

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "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>): No field description available
## sample_rows

legacy · available · api_key, oauth

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

Example row shape only; samples are not analytical evidence.

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "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>): No field description available
## asklear sample

legacy · unavailable · api_key, oauth

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

Example row shape only; samples are not analytical evidence.

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "properties": {
    "dataset": {
      "const": "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>): No field description available
## POST /v1/query_metrics

legacy · available · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing dataset query pricing and account authorization apply.

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

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

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "filters": {
          "description": "Query-specific filters; shared scope belongs in common_filters.",
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        "group_by": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "limit": {
          "default": 100,
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "metrics": {
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        "order_by": {
          "items": {
            "$ref": "#/$defs/Schema2"
          },
          "type": "array"
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema4"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Omit to inherit the main query time; provide for cross-period analysis."
        }
      },
      "required": [
        "name",
        "metrics"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "dir": {
          "default": "asc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "field": {
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "Schema3": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema4": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "additional_queries": {
      "description": "Up to three additional analyses for shares, comparisons, or multiple views.",
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "common_filters": {
      "description": "Filters applied to every query in the bundle.",
      "items": {
        "$ref": "#/$defs/Schema3"
      },
      "type": "array"
    },
    "dataset": {
      "const": "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): Stable PDD product identifier used for exact filtering and paired with the canonical product-detail URL in public results.
- data[].title (string): 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.
- data[].product_url (string): Canonical PDD product-detail URL generated from product_id; it identifies the product reference and requires product-level grouping when used in aggregates.
- data[].shop_id (string): Stable PDD shop identifier used for exact filtering and scope selection; no verified canonical shop URL is available in this release.
- data[].shop (string): Shop name recorded by the PDD source; names can change over time and should be resolved with search_values before use as a filter.
- data[].brand (string): Brand name recorded by the PDD source; values may be empty or vary in spelling, so resolve names before treating them as a filter.
- data[].category_l1 (string): Level-1 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.
- data[].category_l2 (string): Level-2 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.
- data[].category_l3 (string): Level-3 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.
- data[].month (time): Calendar month to which the PDD product sales record belongs, formatted as YYYY-MM; the public dataset grain is monthly.
- data[].billion_subsidy_tag (string): Flag indicating whether the record is associated with PDD's billion-subsidy program; upstream values remain open and are not a closed enum.
- data[].ori_category_l1 (string): Original level-1 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.
- data[].ori_category_l2 (string): Original level-2 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.
- data[].ori_category_l3 (string): Original level-3 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.
- data[].gmv (number): Post-subsidy gross merchandise value calculated as SUM(discount_sales); it is the primary comparable sales amount for this PDD release.
- data[].units (number): Monthly units sold calculated as SUM(count), where count comes from the upstream monthly volume rather than cumulative total_volume.
- data[].asp (number): Weighted average post-subsidy selling price calculated from SUM(discount_sales) divided by SUM(count), with zero-count protection.
## query_metrics

legacy · available · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing dataset query pricing and account authorization apply.

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

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

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "filters": {
          "description": "Query-specific filters; shared scope belongs in common_filters.",
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        "group_by": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "limit": {
          "default": 100,
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "metrics": {
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        "order_by": {
          "items": {
            "$ref": "#/$defs/Schema2"
          },
          "type": "array"
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema4"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Omit to inherit the main query time; provide for cross-period analysis."
        }
      },
      "required": [
        "name",
        "metrics"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "dir": {
          "default": "asc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "field": {
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "Schema3": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema4": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "additional_queries": {
      "description": "Up to three additional analyses for shares, comparisons, or multiple views.",
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "common_filters": {
      "description": "Filters applied to every query in the bundle.",
      "items": {
        "$ref": "#/$defs/Schema3"
      },
      "type": "array"
    },
    "dataset": {
      "const": "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): Stable PDD product identifier used for exact filtering and paired with the canonical product-detail URL in public results.
- data[].title (string): 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.
- data[].product_url (string): Canonical PDD product-detail URL generated from product_id; it identifies the product reference and requires product-level grouping when used in aggregates.
- data[].shop_id (string): Stable PDD shop identifier used for exact filtering and scope selection; no verified canonical shop URL is available in this release.
- data[].shop (string): Shop name recorded by the PDD source; names can change over time and should be resolved with search_values before use as a filter.
- data[].brand (string): Brand name recorded by the PDD source; values may be empty or vary in spelling, so resolve names before treating them as a filter.
- data[].category_l1 (string): Level-1 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.
- data[].category_l2 (string): Level-2 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.
- data[].category_l3 (string): Level-3 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.
- data[].month (time): Calendar month to which the PDD product sales record belongs, formatted as YYYY-MM; the public dataset grain is monthly.
- data[].billion_subsidy_tag (string): Flag indicating whether the record is associated with PDD's billion-subsidy program; upstream values remain open and are not a closed enum.
- data[].ori_category_l1 (string): Original level-1 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.
- data[].ori_category_l2 (string): Original level-2 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.
- data[].ori_category_l3 (string): Original level-3 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.
- data[].gmv (number): Post-subsidy gross merchandise value calculated as SUM(discount_sales); it is the primary comparable sales amount for this PDD release.
- data[].units (number): Monthly units sold calculated as SUM(count), where count comes from the upstream monthly volume rather than cumulative total_volume.
- data[].asp (number): Weighted average post-subsidy selling price calculated from SUM(discount_sales) divided by SUM(count), with zero-count protection.
## asklear query

legacy · unavailable · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing dataset query pricing and account authorization apply.

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

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

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "filters": {
          "description": "Query-specific filters; shared scope belongs in common_filters.",
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        "group_by": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "limit": {
          "default": 100,
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "metrics": {
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        "order_by": {
          "items": {
            "$ref": "#/$defs/Schema2"
          },
          "type": "array"
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema4"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Omit to inherit the main query time; provide for cross-period analysis."
        }
      },
      "required": [
        "name",
        "metrics"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "dir": {
          "default": "asc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "field": {
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "Schema3": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema4": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "additional_queries": {
      "description": "Up to three additional analyses for shares, comparisons, or multiple views.",
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "common_filters": {
      "description": "Filters applied to every query in the bundle.",
      "items": {
        "$ref": "#/$defs/Schema3"
      },
      "type": "array"
    },
    "dataset": {
      "const": "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): Stable PDD product identifier used for exact filtering and paired with the canonical product-detail URL in public results.
- data[].title (string): 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.
- data[].product_url (string): Canonical PDD product-detail URL generated from product_id; it identifies the product reference and requires product-level grouping when used in aggregates.
- data[].shop_id (string): Stable PDD shop identifier used for exact filtering and scope selection; no verified canonical shop URL is available in this release.
- data[].shop (string): Shop name recorded by the PDD source; names can change over time and should be resolved with search_values before use as a filter.
- data[].brand (string): Brand name recorded by the PDD source; values may be empty or vary in spelling, so resolve names before treating them as a filter.
- data[].category_l1 (string): Level-1 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.
- data[].category_l2 (string): Level-2 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.
- data[].category_l3 (string): Level-3 category name in the PDD standard category hierarchy; it is an open upstream value and may be missing.
- data[].month (time): Calendar month to which the PDD product sales record belongs, formatted as YYYY-MM; the public dataset grain is monthly.
- data[].billion_subsidy_tag (string): Flag indicating whether the record is associated with PDD's billion-subsidy program; upstream values remain open and are not a closed enum.
- data[].ori_category_l1 (string): Original level-1 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.
- data[].ori_category_l2 (string): Original level-2 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.
- data[].ori_category_l3 (string): Original level-3 category value supplied by the PDD upstream source; use it for crosswalks rather than assuming it matches the standard category.
- data[].gmv (number): Post-subsidy gross merchandise value calculated as SUM(discount_sales); it is the primary comparable sales amount for this PDD release.
- data[].units (number): Monthly units sold calculated as SUM(count), where count comes from the upstream monthly volume rather than cumulative total_volume.
- data[].asp (number): Weighted average post-subsidy selling price calculated from SUM(discount_sales) divided by SUM(count), with zero-count protection.
## POST /v1/quote

legacy · available · api_key, oauth

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

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

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "filters": {
          "description": "Query-specific filters; shared scope belongs in common_filters.",
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        "group_by": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "limit": {
          "default": 100,
          "maximum": 1000,
          "minimum": 1,
          "type": "integer"
        },
        "metrics": {
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "type": "array"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        },
        "order_by": {
          "items": {
            "$ref": "#/$defs/Schema2"
          },
          "type": "array"
        },
        "time": {
          "anyOf": [
            {
              "$ref": "#/$defs/Schema4"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Omit to inherit the main query time; provide for cross-period analysis."
        }
      },
      "required": [
        "name",
        "metrics"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "dir": {
          "default": "asc",
          "enum": [
            "asc",
            "desc"
          ],
          "type": "string"
        },
        "field": {
          "type": "string"
        }
      },
      "required": [
        "field"
      ],
      "type": "object"
    },
    "Schema3": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema4": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "description": "One flat request shape that FastMCP can expose as tool arguments.",
  "properties": {
    "additional_queries": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Schema1"
          },
          "maxItems": 3,
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "common_filters": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/Schema3"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "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): No field description available
## POST /v1/search_values

legacy · available · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "type": "string"
        },
        "kw": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "limit": {
          "default": 20,
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        }
      },
      "required": [
        "name",
        "field"
      ],
      "type": "object"
    }
  },
  "properties": {
    "additional_searches": {
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "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>): No field description available
## search_values

legacy · available · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "type": "string"
        },
        "kw": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "limit": {
          "default": 20,
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        }
      },
      "required": [
        "name",
        "field"
      ],
      "type": "object"
    }
  },
  "properties": {
    "additional_searches": {
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "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>): No field description available
## asklear search-values

legacy · unavailable · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "type": "string"
        },
        "kw": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "limit": {
          "default": 20,
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
        },
        "name": {
          "pattern": "^[a-z][a-z0-9_]{0,63}$",
          "type": "string"
        }
      },
      "required": [
        "name",
        "field"
      ],
      "type": "object"
    }
  },
  "properties": {
    "additional_searches": {
      "items": {
        "$ref": "#/$defs/Schema1"
      },
      "maxItems": 3,
      "type": "array"
    },
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "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>): No field description available
## POST /v1/query_details

legacy · unavailable · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "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): Stable PDD product identifier used for exact filtering and paired with the canonical product-detail URL in public results.
- data[].title (string): 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.
- data[].shop_id (string): Stable PDD shop identifier used for exact filtering and scope selection; no verified canonical shop URL is available in this release.
- data[].month (time): Calendar month to which the PDD product sales record belongs, formatted as YYYY-MM; the public dataset grain is monthly.
- data[].billion_subsidy_tag (string): Flag indicating whether the record is associated with PDD's billion-subsidy program; upstream values remain open and are not a closed enum.
- data[].platform (string): Constant platform marker identifying these rows as PDD data; it is supplied by the canonical import projection and is not an upstream business field.
- data[].price (number): Listed product price reported by the PDD source; it is a row-level numeric detail field and is not a monthly sales metric.
- data[].count (number): Monthly incremental units from the upstream volume field; do not interpret it as the historical cumulative total_volume value.
- data[].sales (number): Listed-price sales amount derived from the upstream value field; it is retained beside post-subsidy sales for transparent comparison.
- data[].brand_name (string): Raw brand-name column from the PDD source; the canonical brand field is projected from this value and it can be empty.
- data[].shop_name (string): Raw shop-name column from the PDD source; the canonical shop field is projected from this value and names may change.
- data[].tech_date (string): Upstream technical date-like value retained for detail inspection; it is not the sales month and must not drive time analysis.
- data[].category_1 (string): Raw level-1 category-name column from the PDD source, renamed to category_l1 in the public semantic contract.
- data[].category_2 (string): Raw level-2 category-name column from the PDD source, renamed to category_l2 in the public semantic contract.
- data[].category_3 (string): Raw level-3 category-name column from the PDD source, renamed to category_l3 in the public semantic contract.
- data[].total_volume (number): Historical cumulative units reported by the PDD source; it is retained for detail output and must not be used as monthly units.
- data[].total_comment_count (number): Historical cumulative comment count reported by the PDD source; it is a detail field and not a monthly review increment.
- data[].estimate_flag (string): Upstream flag indicating that a source value may be estimated; it is disclosed in detail output but is not exposed as a filter dimension in this release.
- data[].discount_sales (number): Post-subsidy sales amount supplied by the PDD source; it is the physical input used by the public gmv metric.
- data[].ori_category_1 (string): Raw upstream level-1 category value retained for detail output and category crosswalk analysis; it is distinct from category_1.
- data[].ori_category_2 (string): Raw upstream level-2 category value retained for detail output and category crosswalk analysis; it is distinct from category_2.
- data[].ori_category_3 (string): Raw upstream level-3 category value retained for detail output and category crosswalk analysis; it is distinct from category_3.
- data[].product_intro (string): Product introduction text supplied by the PDD source; it is retained for detail output but is not treated as a structured specification.
## query_details

legacy · unavailable · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "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): Stable PDD product identifier used for exact filtering and paired with the canonical product-detail URL in public results.
- data[].title (string): 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.
- data[].shop_id (string): Stable PDD shop identifier used for exact filtering and scope selection; no verified canonical shop URL is available in this release.
- data[].month (time): Calendar month to which the PDD product sales record belongs, formatted as YYYY-MM; the public dataset grain is monthly.
- data[].billion_subsidy_tag (string): Flag indicating whether the record is associated with PDD's billion-subsidy program; upstream values remain open and are not a closed enum.
- data[].platform (string): Constant platform marker identifying these rows as PDD data; it is supplied by the canonical import projection and is not an upstream business field.
- data[].price (number): Listed product price reported by the PDD source; it is a row-level numeric detail field and is not a monthly sales metric.
- data[].count (number): Monthly incremental units from the upstream volume field; do not interpret it as the historical cumulative total_volume value.
- data[].sales (number): Listed-price sales amount derived from the upstream value field; it is retained beside post-subsidy sales for transparent comparison.
- data[].brand_name (string): Raw brand-name column from the PDD source; the canonical brand field is projected from this value and it can be empty.
- data[].shop_name (string): Raw shop-name column from the PDD source; the canonical shop field is projected from this value and names may change.
- data[].tech_date (string): Upstream technical date-like value retained for detail inspection; it is not the sales month and must not drive time analysis.
- data[].category_1 (string): Raw level-1 category-name column from the PDD source, renamed to category_l1 in the public semantic contract.
- data[].category_2 (string): Raw level-2 category-name column from the PDD source, renamed to category_l2 in the public semantic contract.
- data[].category_3 (string): Raw level-3 category-name column from the PDD source, renamed to category_l3 in the public semantic contract.
- data[].total_volume (number): Historical cumulative units reported by the PDD source; it is retained for detail output and must not be used as monthly units.
- data[].total_comment_count (number): Historical cumulative comment count reported by the PDD source; it is a detail field and not a monthly review increment.
- data[].estimate_flag (string): Upstream flag indicating that a source value may be estimated; it is disclosed in detail output but is not exposed as a filter dimension in this release.
- data[].discount_sales (number): Post-subsidy sales amount supplied by the PDD source; it is the physical input used by the public gmv metric.
- data[].ori_category_1 (string): Raw upstream level-1 category value retained for detail output and category crosswalk analysis; it is distinct from category_1.
- data[].ori_category_2 (string): Raw upstream level-2 category value retained for detail output and category crosswalk analysis; it is distinct from category_2.
- data[].ori_category_3 (string): Raw upstream level-3 category value retained for detail output and category crosswalk analysis; it is distinct from category_3.
- data[].product_intro (string): Product introduction text supplied by the PDD source; it is retained for detail output but is not treated as a structured specification.
## asklear query-details

legacy · unavailable · api_key, oauth

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

Monthly grain only
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id or a canonical mobile.yangkeduo.com product URL.
Shops accept an exact shop_id or a shop name aligned through search_values; upstream publishes no shop URL
gmv is the post-subsidy sales amount (upstream value_after_subsidy); the list-price amount is kept in the sales detail field
About 7.3% of rows are marked by upstream as estimates (detail field estimate_flag) and are included in the metrics; that field is not offered as a filter in this release
The total_volume and total_comment_count detail fields are running totals, not monthly values, and must not be mixed with units
The tech_date detail field is an upstream bookkeeping field, not a sale date, and cannot be used for time analysis
brand_name is frequently empty (about 85% for 2026-06); brand rankings drop the empty value
No review, traffic, inventory, causal explanation, or other-platform data is provided
Year-over-year, period-over-period, share, contribution, and cross-period set differences are computed by the agent from atomic query results

Existing pricing applies; metadata reads do not charge Credits.

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

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

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "properties": {
        "field": {
          "description": "Public dimension used to scope the query.",
          "type": "string"
        },
        "op": {
          "description": "Use eq with one platform raw value already returned by search_values or earlier context; use in with all relevant returned raw values.",
          "enum": [
            "eq",
            "neq",
            "in",
            "not_in",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "is_unknown",
            "is_known"
          ],
          "type": "string"
        },
        "value": {
          "anyOf": [
            {},
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Single operand for eq, neq, comparisons, or contains."
        },
        "values": {
          "anyOf": [
            {
              "items": {},
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Platform raw values used by in or not_in."
        }
      },
      "required": [
        "field",
        "op"
      ],
      "type": "object"
    },
    "Schema2": {
      "properties": {
        "end": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive end month/date. Use together with start."
        },
        "grain": {
          "const": "month",
          "default": "month",
          "type": "string"
        },
        "last_complete_months": {
          "anyOf": [
            {
              "maximum": 60,
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Server-resolved latest complete months ending at the authenticated data-through month. Use instead of describe for current/latest/recent monthly questions."
        },
        "start": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Inclusive start month/date. Use together with end."
        }
      },
      "type": "object"
    }
  },
  "properties": {
    "approved_plan_digest": {
      "anyOf": [
        {
          "pattern": "^plan_[0-9a-f]{64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "dataset": {
      "const": "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): Stable PDD product identifier used for exact filtering and paired with the canonical product-detail URL in public results.
- data[].title (string): 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.
- data[].shop_id (string): Stable PDD shop identifier used for exact filtering and scope selection; no verified canonical shop URL is available in this release.
- data[].month (time): Calendar month to which the PDD product sales record belongs, formatted as YYYY-MM; the public dataset grain is monthly.
- data[].billion_subsidy_tag (string): Flag indicating whether the record is associated with PDD's billion-subsidy program; upstream values remain open and are not a closed enum.
- data[].platform (string): Constant platform marker identifying these rows as PDD data; it is supplied by the canonical import projection and is not an upstream business field.
- data[].price (number): Listed product price reported by the PDD source; it is a row-level numeric detail field and is not a monthly sales metric.
- data[].count (number): Monthly incremental units from the upstream volume field; do not interpret it as the historical cumulative total_volume value.
- data[].sales (number): Listed-price sales amount derived from the upstream value field; it is retained beside post-subsidy sales for transparent comparison.
- data[].brand_name (string): Raw brand-name column from the PDD source; the canonical brand field is projected from this value and it can be empty.
- data[].shop_name (string): Raw shop-name column from the PDD source; the canonical shop field is projected from this value and names may change.
- data[].tech_date (string): Upstream technical date-like value retained for detail inspection; it is not the sales month and must not drive time analysis.
- data[].category_1 (string): Raw level-1 category-name column from the PDD source, renamed to category_l1 in the public semantic contract.
- data[].category_2 (string): Raw level-2 category-name column from the PDD source, renamed to category_l2 in the public semantic contract.
- data[].category_3 (string): Raw level-3 category-name column from the PDD source, renamed to category_l3 in the public semantic contract.
- data[].total_volume (number): Historical cumulative units reported by the PDD source; it is retained for detail output and must not be used as monthly units.
- data[].total_comment_count (number): Historical cumulative comment count reported by the PDD source; it is a detail field and not a monthly review increment.
- data[].estimate_flag (string): Upstream flag indicating that a source value may be estimated; it is disclosed in detail output but is not exposed as a filter dimension in this release.
- data[].discount_sales (number): Post-subsidy sales amount supplied by the PDD source; it is the physical input used by the public gmv metric.
- data[].ori_category_1 (string): Raw upstream level-1 category value retained for detail output and category crosswalk analysis; it is distinct from category_1.
- data[].ori_category_2 (string): Raw upstream level-2 category value retained for detail output and category crosswalk analysis; it is distinct from category_2.
- data[].ori_category_3 (string): Raw upstream level-3 category value retained for detail output and category crosswalk analysis; it is distinct from category_3.
- data[].product_intro (string): Product introduction text supplied by the PDD source; it is retained for detail output but is not treated as a structured specification.