# Douyin Monthly Product Sales

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

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

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

Douyin

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

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

## GET /v1/datasets/douyin

legacy · available · api_key, oauth

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

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "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": "douyin"
}
```

### Synthetic response / 合成响应

```json
{
  "dimensions": [
    {
      "desc": "上游记录中的抖音商品稳定标识，用于精确筛选，并与上游商品链接配套。",
      "desc_i18n": {
        "en": "Stable Douyin product identifier from the source record, used for exact filtering and paired with the source product URL.",
        "zh-CN": "上游记录中的抖音商品稳定标识，用于精确筛选，并与上游商品链接配套。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的自然月商品标题，用于结果展示和分组，不作为精确商品筛选条件。",
      "desc_i18n": {
        "en": "Product title recorded by the Douyin source for the calendar month; it is returned for display and grouping, not used as an exact product filter.",
        "zh-CN": "抖音源数据记录的自然月商品标题，用于结果展示和分组，不作为精确商品筛选条件。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "title",
      "query": {
        "filter_operators": [],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据提供的商品详情链接，与 product_id 配套；按源记录返回，不在查询层拼接。",
      "desc_i18n": {
        "en": "Product-detail URL supplied by the Douyin source and paired with product_id; the value is returned as recorded without URL synthesis.",
        "zh-CN": "抖音源数据提供的商品详情链接，与 product_id 配套；按源记录返回，不在查询层拼接。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_url",
      "query": {
        "filter_operators": [],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "上游记录的抖音店铺稳定标识，用于精确店铺筛选及授权后的租户范围选择。",
      "desc_i18n": {
        "en": "Stable Douyin shop identifier recorded by the source, used for exact shop filtering and tenant scope selection when authorized.",
        "zh-CN": "上游记录的抖音店铺稳定标识，用于精确店铺筛选及授权后的租户范围选择。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度店铺名称，名称可能随时间变化，应通过值搜索进行对齐。",
      "desc_i18n": {
        "en": "Shop name recorded by the Douyin source for the product-month row; names may change over time and should be aligned through value search.",
        "zh-CN": "抖音源数据记录的商品月度店铺名称，名称可能随时间变化，应通过值搜索进行对齐。"
      },
      "dictionary_searchable": true,
      "entity_type": "shop",
      "name": "shop",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度卖家标识，按标识返回，不根据店铺名称推断。",
      "desc_i18n": {
        "en": "Seller identifier recorded by the Douyin source for the product-month row; it is returned as an identifier and is not inferred from shop names.",
        "zh-CN": "抖音源数据记录的商品月度卖家标识，按标识返回，不根据店铺名称推断。"
      },
      "dictionary_searchable": false,
      "entity_type": "seller",
      "name": "seller_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度品牌名称，白牌或未分类商品可能为空。",
      "desc_i18n": {
        "en": "Brand name recorded by the Douyin source for the product-month row; the source may leave it empty for unbranded or unclassified products.",
        "zh-CN": "抖音源数据记录的商品月度品牌名称，白牌或未分类商品可能为空。"
      },
      "dictionary_searchable": true,
      "name": "brand",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度末级类目名称，与四级类目层级字段区分。",
      "desc_i18n": {
        "en": "Leaf category name recorded by the Douyin source for the product-month row; it is distinct from the four-level category hierarchy.",
        "zh-CN": "抖音源数据记录的商品月度末级类目名称，与四级类目层级字段区分。"
      },
      "dictionary_searchable": true,
      "name": "category",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度末级类目标识，按源数据返回，不填充缺失值。",
      "desc_i18n": {
        "en": "Leaf category identifier recorded by the Douyin source for the product-month row; it is returned without filling missing source values.",
        "zh-CN": "抖音源数据记录的商品月度末级类目标识，按源数据返回，不填充缺失值。"
      },
      "dictionary_searchable": false,
      "name": "category_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的一级类目标识，与对应的一级类目名称配套。",
      "desc_i18n": {
        "en": "Level-1 category identifier recorded by the Douyin source and paired with the corresponding level-1 category name.",
        "zh-CN": "抖音源数据记录的一级类目标识，与对应的一级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l1_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的一级类目名称，与源层级中的 category_l1_id 配套。",
      "desc_i18n": {
        "en": "Level-1 category name recorded by the Douyin source and paired with category_l1_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的一级类目名称，与源层级中的 category_l1_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l1",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的二级类目标识，与对应的二级类目名称配套。",
      "desc_i18n": {
        "en": "Level-2 category identifier recorded by the Douyin source and paired with the corresponding level-2 category name.",
        "zh-CN": "抖音源数据记录的二级类目标识，与对应的二级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l2_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的二级类目名称，与源层级中的 category_l2_id 配套。",
      "desc_i18n": {
        "en": "Level-2 category name recorded by the Douyin source and paired with category_l2_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的二级类目名称，与源层级中的 category_l2_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l2",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的三级类目标识，与对应的三级类目名称配套。",
      "desc_i18n": {
        "en": "Level-3 category identifier recorded by the Douyin source and paired with the corresponding level-3 category name.",
        "zh-CN": "抖音源数据记录的三级类目标识，与对应的三级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l3_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的三级类目名称，与源层级中的 category_l3_id 配套。",
      "desc_i18n": {
        "en": "Level-3 category name recorded by the Douyin source and paired with category_l3_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的三级类目名称，与源层级中的 category_l3_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l3",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的四级类目标识，与对应的四级类目名称配套。",
      "desc_i18n": {
        "en": "Level-4 category identifier recorded by the Douyin source and paired with the corresponding level-4 category name.",
        "zh-CN": "抖音源数据记录的四级类目标识，与对应的四级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l4_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的四级类目名称，与源层级中的 category_l4_id 配套。",
      "desc_i18n": {
        "en": "Level-4 category name recorded by the Douyin source and paired with category_l4_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的四级类目名称，与源层级中的 category_l4_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l4",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音商品记录所属自然月，是公开的月度时间维度，不等同于采集日期。",
      "desc_i18n": {
        "en": "Calendar month to which the Douyin product record belongs, represented as the public monthly time dimension and not as the collection date.",
        "zh-CN": "抖音商品记录所属自然月，是公开的月度时间维度，不等同于采集日期。"
      },
      "dictionary_searchable": false,
      "name": "month",
      "query": {
        "filter_operators": [],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "time"
    }
  ],
  "metrics": [
    {
      "certified": false,
      "desc": "经过源数据质量验收后，按请求商品和自然月范围对 sales 求和得到的抖音汇总销售额。",
      "desc_i18n": {
        "en": "Aggregated Douyin sales amount calculated as SUM(sales) over the requested product and calendar-month scope after source-quality validation.",
        "zh-CN": "经过源数据质量验收后，按请求商品和自然月范围对 sales 求和得到的抖音汇总销售额。"
      },
      "name": "gmv"
    },
    {
      "certified": false,
      "desc": "完成重复处理验收后，按请求商品和自然月范围对 volume 求和得到的抖音汇总销量。",
      "desc_i18n": {
        "en": "Aggregated Douyin units sold calculated as SUM(volume) over the requested product and calendar-month scope after duplicate handling is validated.",
        "zh-CN": "完成重复处理验收后，按请求商品和自然月范围对 volume 求和得到的抖音汇总销量。"
      },
      "name": "units"
    },
    {
      "certified": false,
      "desc": "按请求范围计算 SUM(sales) 除以 SUM(volume) 的加权平均成交价；总销量为零时返回空值。",
      "desc_i18n": {
        "en": "Weighted average selling price calculated as SUM(sales) divided by SUM(volume) over the requested scope; returns null when total volume is zero.",
        "zh-CN": "按请求范围计算 SUM(sales) 除以 SUM(volume) 的加权平均成交价；总销量为零时返回空值。"
      },
      "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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "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": "douyin"
}
```

### Synthetic response / 合成响应

```json
{
  "dimensions": [
    {
      "desc": "上游记录中的抖音商品稳定标识，用于精确筛选，并与上游商品链接配套。",
      "desc_i18n": {
        "en": "Stable Douyin product identifier from the source record, used for exact filtering and paired with the source product URL.",
        "zh-CN": "上游记录中的抖音商品稳定标识，用于精确筛选，并与上游商品链接配套。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的自然月商品标题，用于结果展示和分组，不作为精确商品筛选条件。",
      "desc_i18n": {
        "en": "Product title recorded by the Douyin source for the calendar month; it is returned for display and grouping, not used as an exact product filter.",
        "zh-CN": "抖音源数据记录的自然月商品标题，用于结果展示和分组，不作为精确商品筛选条件。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "title",
      "query": {
        "filter_operators": [],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据提供的商品详情链接，与 product_id 配套；按源记录返回，不在查询层拼接。",
      "desc_i18n": {
        "en": "Product-detail URL supplied by the Douyin source and paired with product_id; the value is returned as recorded without URL synthesis.",
        "zh-CN": "抖音源数据提供的商品详情链接，与 product_id 配套；按源记录返回，不在查询层拼接。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_url",
      "query": {
        "filter_operators": [],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "上游记录的抖音店铺稳定标识，用于精确店铺筛选及授权后的租户范围选择。",
      "desc_i18n": {
        "en": "Stable Douyin shop identifier recorded by the source, used for exact shop filtering and tenant scope selection when authorized.",
        "zh-CN": "上游记录的抖音店铺稳定标识，用于精确店铺筛选及授权后的租户范围选择。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度店铺名称，名称可能随时间变化，应通过值搜索进行对齐。",
      "desc_i18n": {
        "en": "Shop name recorded by the Douyin source for the product-month row; names may change over time and should be aligned through value search.",
        "zh-CN": "抖音源数据记录的商品月度店铺名称，名称可能随时间变化，应通过值搜索进行对齐。"
      },
      "dictionary_searchable": true,
      "entity_type": "shop",
      "name": "shop",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度卖家标识，按标识返回，不根据店铺名称推断。",
      "desc_i18n": {
        "en": "Seller identifier recorded by the Douyin source for the product-month row; it is returned as an identifier and is not inferred from shop names.",
        "zh-CN": "抖音源数据记录的商品月度卖家标识，按标识返回，不根据店铺名称推断。"
      },
      "dictionary_searchable": false,
      "entity_type": "seller",
      "name": "seller_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度品牌名称，白牌或未分类商品可能为空。",
      "desc_i18n": {
        "en": "Brand name recorded by the Douyin source for the product-month row; the source may leave it empty for unbranded or unclassified products.",
        "zh-CN": "抖音源数据记录的商品月度品牌名称，白牌或未分类商品可能为空。"
      },
      "dictionary_searchable": true,
      "name": "brand",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度末级类目名称，与四级类目层级字段区分。",
      "desc_i18n": {
        "en": "Leaf category name recorded by the Douyin source for the product-month row; it is distinct from the four-level category hierarchy.",
        "zh-CN": "抖音源数据记录的商品月度末级类目名称，与四级类目层级字段区分。"
      },
      "dictionary_searchable": true,
      "name": "category",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度末级类目标识，按源数据返回，不填充缺失值。",
      "desc_i18n": {
        "en": "Leaf category identifier recorded by the Douyin source for the product-month row; it is returned without filling missing source values.",
        "zh-CN": "抖音源数据记录的商品月度末级类目标识，按源数据返回，不填充缺失值。"
      },
      "dictionary_searchable": false,
      "name": "category_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的一级类目标识，与对应的一级类目名称配套。",
      "desc_i18n": {
        "en": "Level-1 category identifier recorded by the Douyin source and paired with the corresponding level-1 category name.",
        "zh-CN": "抖音源数据记录的一级类目标识，与对应的一级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l1_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的一级类目名称，与源层级中的 category_l1_id 配套。",
      "desc_i18n": {
        "en": "Level-1 category name recorded by the Douyin source and paired with category_l1_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的一级类目名称，与源层级中的 category_l1_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l1",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的二级类目标识，与对应的二级类目名称配套。",
      "desc_i18n": {
        "en": "Level-2 category identifier recorded by the Douyin source and paired with the corresponding level-2 category name.",
        "zh-CN": "抖音源数据记录的二级类目标识，与对应的二级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l2_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的二级类目名称，与源层级中的 category_l2_id 配套。",
      "desc_i18n": {
        "en": "Level-2 category name recorded by the Douyin source and paired with category_l2_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的二级类目名称，与源层级中的 category_l2_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l2",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的三级类目标识，与对应的三级类目名称配套。",
      "desc_i18n": {
        "en": "Level-3 category identifier recorded by the Douyin source and paired with the corresponding level-3 category name.",
        "zh-CN": "抖音源数据记录的三级类目标识，与对应的三级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l3_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的三级类目名称，与源层级中的 category_l3_id 配套。",
      "desc_i18n": {
        "en": "Level-3 category name recorded by the Douyin source and paired with category_l3_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的三级类目名称，与源层级中的 category_l3_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l3",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的四级类目标识，与对应的四级类目名称配套。",
      "desc_i18n": {
        "en": "Level-4 category identifier recorded by the Douyin source and paired with the corresponding level-4 category name.",
        "zh-CN": "抖音源数据记录的四级类目标识，与对应的四级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l4_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的四级类目名称，与源层级中的 category_l4_id 配套。",
      "desc_i18n": {
        "en": "Level-4 category name recorded by the Douyin source and paired with category_l4_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的四级类目名称，与源层级中的 category_l4_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l4",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音商品记录所属自然月，是公开的月度时间维度，不等同于采集日期。",
      "desc_i18n": {
        "en": "Calendar month to which the Douyin product record belongs, represented as the public monthly time dimension and not as the collection date.",
        "zh-CN": "抖音商品记录所属自然月，是公开的月度时间维度，不等同于采集日期。"
      },
      "dictionary_searchable": false,
      "name": "month",
      "query": {
        "filter_operators": [],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "time"
    }
  ],
  "metrics": [
    {
      "certified": false,
      "desc": "经过源数据质量验收后，按请求商品和自然月范围对 sales 求和得到的抖音汇总销售额。",
      "desc_i18n": {
        "en": "Aggregated Douyin sales amount calculated as SUM(sales) over the requested product and calendar-month scope after source-quality validation.",
        "zh-CN": "经过源数据质量验收后，按请求商品和自然月范围对 sales 求和得到的抖音汇总销售额。"
      },
      "name": "gmv"
    },
    {
      "certified": false,
      "desc": "完成重复处理验收后，按请求商品和自然月范围对 volume 求和得到的抖音汇总销量。",
      "desc_i18n": {
        "en": "Aggregated Douyin units sold calculated as SUM(volume) over the requested product and calendar-month scope after duplicate handling is validated.",
        "zh-CN": "完成重复处理验收后，按请求商品和自然月范围对 volume 求和得到的抖音汇总销量。"
      },
      "name": "units"
    },
    {
      "certified": false,
      "desc": "按请求范围计算 SUM(sales) 除以 SUM(volume) 的加权平均成交价；总销量为零时返回空值。",
      "desc_i18n": {
        "en": "Weighted average selling price calculated as SUM(sales) divided by SUM(volume) over the requested scope; returns null when total volume is zero.",
        "zh-CN": "按请求范围计算 SUM(sales) 除以 SUM(volume) 的加权平均成交价；总销量为零时返回空值。"
      },
      "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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "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": "douyin"
}
```

### Synthetic response / 合成响应

```json
{
  "dimensions": [
    {
      "desc": "上游记录中的抖音商品稳定标识，用于精确筛选，并与上游商品链接配套。",
      "desc_i18n": {
        "en": "Stable Douyin product identifier from the source record, used for exact filtering and paired with the source product URL.",
        "zh-CN": "上游记录中的抖音商品稳定标识，用于精确筛选，并与上游商品链接配套。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的自然月商品标题，用于结果展示和分组，不作为精确商品筛选条件。",
      "desc_i18n": {
        "en": "Product title recorded by the Douyin source for the calendar month; it is returned for display and grouping, not used as an exact product filter.",
        "zh-CN": "抖音源数据记录的自然月商品标题，用于结果展示和分组，不作为精确商品筛选条件。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "title",
      "query": {
        "filter_operators": [],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据提供的商品详情链接，与 product_id 配套；按源记录返回，不在查询层拼接。",
      "desc_i18n": {
        "en": "Product-detail URL supplied by the Douyin source and paired with product_id; the value is returned as recorded without URL synthesis.",
        "zh-CN": "抖音源数据提供的商品详情链接，与 product_id 配套；按源记录返回，不在查询层拼接。"
      },
      "dictionary_searchable": false,
      "entity_type": "product",
      "name": "product_url",
      "query": {
        "filter_operators": [],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "上游记录的抖音店铺稳定标识，用于精确店铺筛选及授权后的租户范围选择。",
      "desc_i18n": {
        "en": "Stable Douyin shop identifier recorded by the source, used for exact shop filtering and tenant scope selection when authorized.",
        "zh-CN": "上游记录的抖音店铺稳定标识，用于精确店铺筛选及授权后的租户范围选择。"
      },
      "dictionary_searchable": false,
      "entity_type": "shop",
      "name": "shop_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度店铺名称，名称可能随时间变化，应通过值搜索进行对齐。",
      "desc_i18n": {
        "en": "Shop name recorded by the Douyin source for the product-month row; names may change over time and should be aligned through value search.",
        "zh-CN": "抖音源数据记录的商品月度店铺名称，名称可能随时间变化，应通过值搜索进行对齐。"
      },
      "dictionary_searchable": true,
      "entity_type": "shop",
      "name": "shop",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度卖家标识，按标识返回，不根据店铺名称推断。",
      "desc_i18n": {
        "en": "Seller identifier recorded by the Douyin source for the product-month row; it is returned as an identifier and is not inferred from shop names.",
        "zh-CN": "抖音源数据记录的商品月度卖家标识，按标识返回，不根据店铺名称推断。"
      },
      "dictionary_searchable": false,
      "entity_type": "seller",
      "name": "seller_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度品牌名称，白牌或未分类商品可能为空。",
      "desc_i18n": {
        "en": "Brand name recorded by the Douyin source for the product-month row; the source may leave it empty for unbranded or unclassified products.",
        "zh-CN": "抖音源数据记录的商品月度品牌名称，白牌或未分类商品可能为空。"
      },
      "dictionary_searchable": true,
      "name": "brand",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度末级类目名称，与四级类目层级字段区分。",
      "desc_i18n": {
        "en": "Leaf category name recorded by the Douyin source for the product-month row; it is distinct from the four-level category hierarchy.",
        "zh-CN": "抖音源数据记录的商品月度末级类目名称，与四级类目层级字段区分。"
      },
      "dictionary_searchable": true,
      "name": "category",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的商品月度末级类目标识，按源数据返回，不填充缺失值。",
      "desc_i18n": {
        "en": "Leaf category identifier recorded by the Douyin source for the product-month row; it is returned without filling missing source values.",
        "zh-CN": "抖音源数据记录的商品月度末级类目标识，按源数据返回，不填充缺失值。"
      },
      "dictionary_searchable": false,
      "name": "category_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的一级类目标识，与对应的一级类目名称配套。",
      "desc_i18n": {
        "en": "Level-1 category identifier recorded by the Douyin source and paired with the corresponding level-1 category name.",
        "zh-CN": "抖音源数据记录的一级类目标识，与对应的一级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l1_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的一级类目名称，与源层级中的 category_l1_id 配套。",
      "desc_i18n": {
        "en": "Level-1 category name recorded by the Douyin source and paired with category_l1_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的一级类目名称，与源层级中的 category_l1_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l1",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的二级类目标识，与对应的二级类目名称配套。",
      "desc_i18n": {
        "en": "Level-2 category identifier recorded by the Douyin source and paired with the corresponding level-2 category name.",
        "zh-CN": "抖音源数据记录的二级类目标识，与对应的二级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l2_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的二级类目名称，与源层级中的 category_l2_id 配套。",
      "desc_i18n": {
        "en": "Level-2 category name recorded by the Douyin source and paired with category_l2_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的二级类目名称，与源层级中的 category_l2_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l2",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的三级类目标识，与对应的三级类目名称配套。",
      "desc_i18n": {
        "en": "Level-3 category identifier recorded by the Douyin source and paired with the corresponding level-3 category name.",
        "zh-CN": "抖音源数据记录的三级类目标识，与对应的三级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l3_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的三级类目名称，与源层级中的 category_l3_id 配套。",
      "desc_i18n": {
        "en": "Level-3 category name recorded by the Douyin source and paired with category_l3_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的三级类目名称，与源层级中的 category_l3_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l3",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的四级类目标识，与对应的四级类目名称配套。",
      "desc_i18n": {
        "en": "Level-4 category identifier recorded by the Douyin source and paired with the corresponding level-4 category name.",
        "zh-CN": "抖音源数据记录的四级类目标识，与对应的四级类目名称配套。"
      },
      "dictionary_searchable": false,
      "name": "category_l4_id",
      "query": {
        "filter_operators": [
          "eq",
          "in"
        ],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音源数据记录的四级类目名称，与源层级中的 category_l4_id 配套。",
      "desc_i18n": {
        "en": "Level-4 category name recorded by the Douyin source and paired with category_l4_id in the source hierarchy.",
        "zh-CN": "抖音源数据记录的四级类目名称，与源层级中的 category_l4_id 配套。"
      },
      "dictionary_searchable": true,
      "name": "category_l4",
      "query": {
        "filter_operators": [
          "eq",
          "neq",
          "in",
          "not_in",
          "contains"
        ],
        "groupable": true,
        "searchable": true,
        "sortable": true
      },
      "reference_formats": [],
      "type": "string"
    },
    {
      "desc": "抖音商品记录所属自然月，是公开的月度时间维度，不等同于采集日期。",
      "desc_i18n": {
        "en": "Calendar month to which the Douyin product record belongs, represented as the public monthly time dimension and not as the collection date.",
        "zh-CN": "抖音商品记录所属自然月，是公开的月度时间维度，不等同于采集日期。"
      },
      "dictionary_searchable": false,
      "name": "month",
      "query": {
        "filter_operators": [],
        "groupable": true,
        "searchable": false,
        "sortable": true
      },
      "reference_formats": [],
      "type": "time"
    }
  ],
  "metrics": [
    {
      "certified": false,
      "desc": "经过源数据质量验收后，按请求商品和自然月范围对 sales 求和得到的抖音汇总销售额。",
      "desc_i18n": {
        "en": "Aggregated Douyin sales amount calculated as SUM(sales) over the requested product and calendar-month scope after source-quality validation.",
        "zh-CN": "经过源数据质量验收后，按请求商品和自然月范围对 sales 求和得到的抖音汇总销售额。"
      },
      "name": "gmv"
    },
    {
      "certified": false,
      "desc": "完成重复处理验收后，按请求商品和自然月范围对 volume 求和得到的抖音汇总销量。",
      "desc_i18n": {
        "en": "Aggregated Douyin units sold calculated as SUM(volume) over the requested product and calendar-month scope after duplicate handling is validated.",
        "zh-CN": "完成重复处理验收后，按请求商品和自然月范围对 volume 求和得到的抖音汇总销量。"
      },
      "name": "units"
    },
    {
      "certified": false,
      "desc": "按请求范围计算 SUM(sales) 除以 SUM(volume) 的加权平均成交价；总销量为零时返回空值。",
      "desc_i18n": {
        "en": "Weighted average selling price calculated as SUM(sales) divided by SUM(volume) over the requested scope; returns null when total volume is zero.",
        "zh-CN": "按请求范围计算 SUM(sales) 除以 SUM(volume) 的加权平均成交价；总销量为零时返回空值。"
      },
      "name": "asp"
    }
  ]
}
```

- dimensions (array<object>): No field description available
- metrics (array<object>): No field description available
## GET /v1/datasets/douyin/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": "douyin"
    },
    "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": "douyin",
  "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": "douyin"
    },
    "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": "douyin",
  "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": "douyin"
    },
    "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": "douyin",
  "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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "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",
          "seller_id",
          "brand",
          "category",
          "category_id",
          "category_l1_id",
          "category_l1",
          "category_l2_id",
          "category_l2",
          "category_l3_id",
          "category_l3",
          "category_l4_id",
          "category_l4",
          "month"
        ]
      },
      "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": "douyin",
  "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": "douyin"
  }
}
```

- data[].product_id (string): Stable Douyin product identifier from the source record, used for exact filtering and paired with the source product URL.
- data[].title (string): Product title recorded by the Douyin source for the calendar month; it is returned for display and grouping, not used as an exact product filter.
- data[].product_url (string): Product-detail URL supplied by the Douyin source and paired with product_id; the value is returned as recorded without URL synthesis.
- data[].shop_id (string): Stable Douyin shop identifier recorded by the source, used for exact shop filtering and tenant scope selection when authorized.
- data[].shop (string): Shop name recorded by the Douyin source for the product-month row; names may change over time and should be aligned through value search.
- data[].seller_id (string): Seller identifier recorded by the Douyin source for the product-month row; it is returned as an identifier and is not inferred from shop names.
- data[].brand (string): Brand name recorded by the Douyin source for the product-month row; the source may leave it empty for unbranded or unclassified products.
- data[].category (string): Leaf category name recorded by the Douyin source for the product-month row; it is distinct from the four-level category hierarchy.
- data[].category_id (string): Leaf category identifier recorded by the Douyin source for the product-month row; it is returned without filling missing source values.
- data[].category_l1_id (string): Level-1 category identifier recorded by the Douyin source and paired with the corresponding level-1 category name.
- data[].category_l1 (string): Level-1 category name recorded by the Douyin source and paired with category_l1_id in the source hierarchy.
- data[].category_l2_id (string): Level-2 category identifier recorded by the Douyin source and paired with the corresponding level-2 category name.
- data[].category_l2 (string): Level-2 category name recorded by the Douyin source and paired with category_l2_id in the source hierarchy.
- data[].category_l3_id (string): Level-3 category identifier recorded by the Douyin source and paired with the corresponding level-3 category name.
- data[].category_l3 (string): Level-3 category name recorded by the Douyin source and paired with category_l3_id in the source hierarchy.
- data[].category_l4_id (string): Level-4 category identifier recorded by the Douyin source and paired with the corresponding level-4 category name.
- data[].category_l4 (string): Level-4 category name recorded by the Douyin source and paired with category_l4_id in the source hierarchy.
- data[].month (time): Calendar month to which the Douyin product record belongs, represented as the public monthly time dimension and not as the collection date.
- data[].gmv (number): Aggregated Douyin sales amount calculated as SUM(sales) over the requested product and calendar-month scope after source-quality validation.
- data[].units (number): Aggregated Douyin units sold calculated as SUM(volume) over the requested product and calendar-month scope after duplicate handling is validated.
- data[].asp (number): Weighted average selling price calculated as SUM(sales) divided by SUM(volume) over the requested scope; returns null when total volume is zero.
## 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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "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",
          "seller_id",
          "brand",
          "category",
          "category_id",
          "category_l1_id",
          "category_l1",
          "category_l2_id",
          "category_l2",
          "category_l3_id",
          "category_l3",
          "category_l4_id",
          "category_l4",
          "month"
        ]
      },
      "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": "douyin",
  "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": "douyin"
  }
}
```

- data[].product_id (string): Stable Douyin product identifier from the source record, used for exact filtering and paired with the source product URL.
- data[].title (string): Product title recorded by the Douyin source for the calendar month; it is returned for display and grouping, not used as an exact product filter.
- data[].product_url (string): Product-detail URL supplied by the Douyin source and paired with product_id; the value is returned as recorded without URL synthesis.
- data[].shop_id (string): Stable Douyin shop identifier recorded by the source, used for exact shop filtering and tenant scope selection when authorized.
- data[].shop (string): Shop name recorded by the Douyin source for the product-month row; names may change over time and should be aligned through value search.
- data[].seller_id (string): Seller identifier recorded by the Douyin source for the product-month row; it is returned as an identifier and is not inferred from shop names.
- data[].brand (string): Brand name recorded by the Douyin source for the product-month row; the source may leave it empty for unbranded or unclassified products.
- data[].category (string): Leaf category name recorded by the Douyin source for the product-month row; it is distinct from the four-level category hierarchy.
- data[].category_id (string): Leaf category identifier recorded by the Douyin source for the product-month row; it is returned without filling missing source values.
- data[].category_l1_id (string): Level-1 category identifier recorded by the Douyin source and paired with the corresponding level-1 category name.
- data[].category_l1 (string): Level-1 category name recorded by the Douyin source and paired with category_l1_id in the source hierarchy.
- data[].category_l2_id (string): Level-2 category identifier recorded by the Douyin source and paired with the corresponding level-2 category name.
- data[].category_l2 (string): Level-2 category name recorded by the Douyin source and paired with category_l2_id in the source hierarchy.
- data[].category_l3_id (string): Level-3 category identifier recorded by the Douyin source and paired with the corresponding level-3 category name.
- data[].category_l3 (string): Level-3 category name recorded by the Douyin source and paired with category_l3_id in the source hierarchy.
- data[].category_l4_id (string): Level-4 category identifier recorded by the Douyin source and paired with the corresponding level-4 category name.
- data[].category_l4 (string): Level-4 category name recorded by the Douyin source and paired with category_l4_id in the source hierarchy.
- data[].month (time): Calendar month to which the Douyin product record belongs, represented as the public monthly time dimension and not as the collection date.
- data[].gmv (number): Aggregated Douyin sales amount calculated as SUM(sales) over the requested product and calendar-month scope after source-quality validation.
- data[].units (number): Aggregated Douyin units sold calculated as SUM(volume) over the requested product and calendar-month scope after duplicate handling is validated.
- data[].asp (number): Weighted average selling price calculated as SUM(sales) divided by SUM(volume) over the requested scope; returns null when total volume is zero.
## 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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "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",
          "seller_id",
          "brand",
          "category",
          "category_id",
          "category_l1_id",
          "category_l1",
          "category_l2_id",
          "category_l2",
          "category_l3_id",
          "category_l3",
          "category_l4_id",
          "category_l4",
          "month"
        ]
      },
      "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": "douyin",
  "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": "douyin"
  }
}
```

- data[].product_id (string): Stable Douyin product identifier from the source record, used for exact filtering and paired with the source product URL.
- data[].title (string): Product title recorded by the Douyin source for the calendar month; it is returned for display and grouping, not used as an exact product filter.
- data[].product_url (string): Product-detail URL supplied by the Douyin source and paired with product_id; the value is returned as recorded without URL synthesis.
- data[].shop_id (string): Stable Douyin shop identifier recorded by the source, used for exact shop filtering and tenant scope selection when authorized.
- data[].shop (string): Shop name recorded by the Douyin source for the product-month row; names may change over time and should be aligned through value search.
- data[].seller_id (string): Seller identifier recorded by the Douyin source for the product-month row; it is returned as an identifier and is not inferred from shop names.
- data[].brand (string): Brand name recorded by the Douyin source for the product-month row; the source may leave it empty for unbranded or unclassified products.
- data[].category (string): Leaf category name recorded by the Douyin source for the product-month row; it is distinct from the four-level category hierarchy.
- data[].category_id (string): Leaf category identifier recorded by the Douyin source for the product-month row; it is returned without filling missing source values.
- data[].category_l1_id (string): Level-1 category identifier recorded by the Douyin source and paired with the corresponding level-1 category name.
- data[].category_l1 (string): Level-1 category name recorded by the Douyin source and paired with category_l1_id in the source hierarchy.
- data[].category_l2_id (string): Level-2 category identifier recorded by the Douyin source and paired with the corresponding level-2 category name.
- data[].category_l2 (string): Level-2 category name recorded by the Douyin source and paired with category_l2_id in the source hierarchy.
- data[].category_l3_id (string): Level-3 category identifier recorded by the Douyin source and paired with the corresponding level-3 category name.
- data[].category_l3 (string): Level-3 category name recorded by the Douyin source and paired with category_l3_id in the source hierarchy.
- data[].category_l4_id (string): Level-4 category identifier recorded by the Douyin source and paired with the corresponding level-4 category name.
- data[].category_l4 (string): Level-4 category name recorded by the Douyin source and paired with category_l4_id in the source hierarchy.
- data[].month (time): Calendar month to which the Douyin product record belongs, represented as the public monthly time dimension and not as the collection date.
- data[].gmv (number): Aggregated Douyin sales amount calculated as SUM(sales) over the requested product and calendar-month scope after source-quality validation.
- data[].units (number): Aggregated Douyin units sold calculated as SUM(volume) over the requested product and calendar-month scope after duplicate handling is validated.
- data[].asp (number): Weighted average selling price calculated as SUM(sales) divided by SUM(volume) over the requested scope; returns null when total volume is zero.
## 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": "douyin"
    },
    "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": "douyin",
  "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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "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": "douyin",
  "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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "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": "douyin",
  "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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "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": "douyin",
  "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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "fields": {
      "description": "Raw detail output fields. Use query_metrics for rankings and product or shop links.",
      "items": {
        "enum": [
          "product_id",
          "title",
          "product_url",
          "shop_id",
          "shop",
          "seller_id",
          "brand",
          "category",
          "category_id",
          "category_l1_id",
          "category_l1",
          "category_l2_id",
          "category_l2",
          "category_l3_id",
          "category_l3",
          "category_l4_id",
          "category_l4",
          "price",
          "is_first_seen",
          "month",
          "sales",
          "volume"
        ]
      },
      "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": "douyin",
  "fields": [
    "product_id",
    "title",
    "product_url"
  ],
  "filters": [
    {
      "field": "product_id",
      "op": "eq",
      "value": "1234567890"
    }
  ],
  "limit": 10,
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

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

- data[].product_id (string): Stable Douyin product identifier from the source record, used for exact filtering and paired with the source product URL.
- data[].title (string): Product title recorded by the Douyin source for the calendar month; it is returned for display and grouping, not used as an exact product filter.
- data[].product_url (string): Product-detail URL supplied by the Douyin source and paired with product_id; the value is returned as recorded without URL synthesis.
- data[].shop_id (string): Stable Douyin shop identifier recorded by the source, used for exact shop filtering and tenant scope selection when authorized.
- data[].shop (string): Shop name recorded by the Douyin source for the product-month row; names may change over time and should be aligned through value search.
- data[].seller_id (string): Seller identifier recorded by the Douyin source for the product-month row; it is returned as an identifier and is not inferred from shop names.
- data[].brand (string): Brand name recorded by the Douyin source for the product-month row; the source may leave it empty for unbranded or unclassified products.
- data[].category (string): Leaf category name recorded by the Douyin source for the product-month row; it is distinct from the four-level category hierarchy.
- data[].category_id (string): Leaf category identifier recorded by the Douyin source for the product-month row; it is returned without filling missing source values.
- data[].category_l1_id (string): Level-1 category identifier recorded by the Douyin source and paired with the corresponding level-1 category name.
- data[].category_l1 (string): Level-1 category name recorded by the Douyin source and paired with category_l1_id in the source hierarchy.
- data[].category_l2_id (string): Level-2 category identifier recorded by the Douyin source and paired with the corresponding level-2 category name.
- data[].category_l2 (string): Level-2 category name recorded by the Douyin source and paired with category_l2_id in the source hierarchy.
- data[].category_l3_id (string): Level-3 category identifier recorded by the Douyin source and paired with the corresponding level-3 category name.
- data[].category_l3 (string): Level-3 category name recorded by the Douyin source and paired with category_l3_id in the source hierarchy.
- data[].category_l4_id (string): Level-4 category identifier recorded by the Douyin source and paired with the corresponding level-4 category name.
- data[].category_l4 (string): Level-4 category name recorded by the Douyin source and paired with category_l4_id in the source hierarchy.
- data[].price (number): Product price recorded by the Douyin source for the product-month row; it is a detail value and is not used as a monthly sales aggregate.
- data[].is_first_seen (integer): First-seen marker recorded by the Douyin source for the product-month row; its source meaning is preserved without deriving a new date.
- data[].month (time): Calendar month to which the Douyin product record belongs, represented as the public monthly time dimension and not as the collection date.
- data[].sales (number): Raw sales amount recorded by the Douyin source for one product-month row; aggregation uses SUM(sales) after the reviewed source grain is confirmed.
- data[].volume (integer): Raw units volume recorded by the Douyin source for one product-month row; aggregation uses SUM(volume) after duplicate handling is reviewed.
## 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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "fields": {
      "description": "Raw detail output fields. Use query_metrics for rankings and product or shop links.",
      "items": {
        "enum": [
          "product_id",
          "title",
          "product_url",
          "shop_id",
          "shop",
          "seller_id",
          "brand",
          "category",
          "category_id",
          "category_l1_id",
          "category_l1",
          "category_l2_id",
          "category_l2",
          "category_l3_id",
          "category_l3",
          "category_l4_id",
          "category_l4",
          "price",
          "is_first_seen",
          "month",
          "sales",
          "volume"
        ]
      },
      "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": "douyin",
  "fields": [
    "product_id",
    "title",
    "product_url"
  ],
  "filters": [
    {
      "field": "product_id",
      "op": "eq",
      "value": "1234567890"
    }
  ],
  "idempotency_key": "directory-example",
  "limit": 10,
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

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

- data[].product_id (string): Stable Douyin product identifier from the source record, used for exact filtering and paired with the source product URL.
- data[].title (string): Product title recorded by the Douyin source for the calendar month; it is returned for display and grouping, not used as an exact product filter.
- data[].product_url (string): Product-detail URL supplied by the Douyin source and paired with product_id; the value is returned as recorded without URL synthesis.
- data[].shop_id (string): Stable Douyin shop identifier recorded by the source, used for exact shop filtering and tenant scope selection when authorized.
- data[].shop (string): Shop name recorded by the Douyin source for the product-month row; names may change over time and should be aligned through value search.
- data[].seller_id (string): Seller identifier recorded by the Douyin source for the product-month row; it is returned as an identifier and is not inferred from shop names.
- data[].brand (string): Brand name recorded by the Douyin source for the product-month row; the source may leave it empty for unbranded or unclassified products.
- data[].category (string): Leaf category name recorded by the Douyin source for the product-month row; it is distinct from the four-level category hierarchy.
- data[].category_id (string): Leaf category identifier recorded by the Douyin source for the product-month row; it is returned without filling missing source values.
- data[].category_l1_id (string): Level-1 category identifier recorded by the Douyin source and paired with the corresponding level-1 category name.
- data[].category_l1 (string): Level-1 category name recorded by the Douyin source and paired with category_l1_id in the source hierarchy.
- data[].category_l2_id (string): Level-2 category identifier recorded by the Douyin source and paired with the corresponding level-2 category name.
- data[].category_l2 (string): Level-2 category name recorded by the Douyin source and paired with category_l2_id in the source hierarchy.
- data[].category_l3_id (string): Level-3 category identifier recorded by the Douyin source and paired with the corresponding level-3 category name.
- data[].category_l3 (string): Level-3 category name recorded by the Douyin source and paired with category_l3_id in the source hierarchy.
- data[].category_l4_id (string): Level-4 category identifier recorded by the Douyin source and paired with the corresponding level-4 category name.
- data[].category_l4 (string): Level-4 category name recorded by the Douyin source and paired with category_l4_id in the source hierarchy.
- data[].price (number): Product price recorded by the Douyin source for the product-month row; it is a detail value and is not used as a monthly sales aggregate.
- data[].is_first_seen (integer): First-seen marker recorded by the Douyin source for the product-month row; its source meaning is preserved without deriving a new date.
- data[].month (time): Calendar month to which the Douyin product record belongs, represented as the public monthly time dimension and not as the collection date.
- data[].sales (number): Raw sales amount recorded by the Douyin source for one product-month row; aggregation uses SUM(sales) after the reviewed source grain is confirmed.
- data[].volume (integer): Raw units volume recorded by the Douyin source for one product-month row; aggregation uses SUM(volume) after duplicate handling is reviewed.
## 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.

Data is partitioned by calendar month.
search_products finds product identity candidates by name or title; product filters in query_metrics and query_details still require an exact product_id because this dataset does not expose a standard product URL filter.
Shops accept an exact shop_id or a shop name aligned with search_values.
Reviews, traffic, inventory, causal explanations, and other platform data are not provided.
YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results.
Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation.
The catalog currently registers the 2026-06 month; coverage, duplicate-row handling, and metric definitions remain pending confirmation.

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": "douyin"
    },
    "dry_run": {
      "default": false,
      "type": "boolean"
    },
    "fields": {
      "description": "Raw detail output fields. Use query_metrics for rankings and product or shop links.",
      "items": {
        "enum": [
          "product_id",
          "title",
          "product_url",
          "shop_id",
          "shop",
          "seller_id",
          "brand",
          "category",
          "category_id",
          "category_l1_id",
          "category_l1",
          "category_l2_id",
          "category_l2",
          "category_l3_id",
          "category_l3",
          "category_l4_id",
          "category_l4",
          "price",
          "is_first_seen",
          "month",
          "sales",
          "volume"
        ]
      },
      "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": "douyin",
  "fields": [
    "product_id",
    "title",
    "product_url"
  ],
  "filters": [
    {
      "field": "product_id",
      "op": "eq",
      "value": "1234567890"
    }
  ],
  "idempotency_key": "directory-example",
  "limit": 10,
  "time": {
    "last_complete_months": 1
  }
}
```

### Synthetic response / 合成响应

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

- data[].product_id (string): Stable Douyin product identifier from the source record, used for exact filtering and paired with the source product URL.
- data[].title (string): Product title recorded by the Douyin source for the calendar month; it is returned for display and grouping, not used as an exact product filter.
- data[].product_url (string): Product-detail URL supplied by the Douyin source and paired with product_id; the value is returned as recorded without URL synthesis.
- data[].shop_id (string): Stable Douyin shop identifier recorded by the source, used for exact shop filtering and tenant scope selection when authorized.
- data[].shop (string): Shop name recorded by the Douyin source for the product-month row; names may change over time and should be aligned through value search.
- data[].seller_id (string): Seller identifier recorded by the Douyin source for the product-month row; it is returned as an identifier and is not inferred from shop names.
- data[].brand (string): Brand name recorded by the Douyin source for the product-month row; the source may leave it empty for unbranded or unclassified products.
- data[].category (string): Leaf category name recorded by the Douyin source for the product-month row; it is distinct from the four-level category hierarchy.
- data[].category_id (string): Leaf category identifier recorded by the Douyin source for the product-month row; it is returned without filling missing source values.
- data[].category_l1_id (string): Level-1 category identifier recorded by the Douyin source and paired with the corresponding level-1 category name.
- data[].category_l1 (string): Level-1 category name recorded by the Douyin source and paired with category_l1_id in the source hierarchy.
- data[].category_l2_id (string): Level-2 category identifier recorded by the Douyin source and paired with the corresponding level-2 category name.
- data[].category_l2 (string): Level-2 category name recorded by the Douyin source and paired with category_l2_id in the source hierarchy.
- data[].category_l3_id (string): Level-3 category identifier recorded by the Douyin source and paired with the corresponding level-3 category name.
- data[].category_l3 (string): Level-3 category name recorded by the Douyin source and paired with category_l3_id in the source hierarchy.
- data[].category_l4_id (string): Level-4 category identifier recorded by the Douyin source and paired with the corresponding level-4 category name.
- data[].category_l4 (string): Level-4 category name recorded by the Douyin source and paired with category_l4_id in the source hierarchy.
- data[].price (number): Product price recorded by the Douyin source for the product-month row; it is a detail value and is not used as a monthly sales aggregate.
- data[].is_first_seen (integer): First-seen marker recorded by the Douyin source for the product-month row; its source meaning is preserved without deriving a new date.
- data[].month (time): Calendar month to which the Douyin product record belongs, represented as the public monthly time dimension and not as the collection date.
- data[].sales (number): Raw sales amount recorded by the Douyin source for one product-month row; aggregation uses SUM(sales) after the reviewed source grain is confirmed.
- data[].volume (integer): Raw units volume recorded by the Douyin source for one product-month row; aggregation uses SUM(volume) after duplicate handling is reviewed.