---
document_id: agent.dataset.douyin
schema_version: 2
parent_document_id: agent.capabilities
section: capabilities
---

<!-- Generated by scripts.build_agent_guide; do not edit. -->

# Douyin Monthly Product Sales / 抖音商品月度销量明细表

This page describes the public contract and static sample; authenticated tools and runtime responses are authoritative for current access and time coverage.
此页提供公开契约和静态样例；当前访问与覆盖范围以认证后的工具面和运行时响应为准。

- Platform / 平台: Douyin / 抖音
- API ID: `dataset=douyin`
- Time grain / 时间粒度: `month`
- Entity types / 实体类型: `product, shop`
- Filter fields / 可筛选字段: `product_id, shop_id, brand, category_l1_id, category_l1, category_l2_id, category_l2, category_l3_id, category_l3, category_l4_id, category_l4, shop`

## Minimal call / 最小调用

`query_metrics`

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


## Fields and capabilities / 字段与能力

- `product_id` — Stable Douyin product identifier intended for exact filtering and paired with product_url. / 抖音商品的稳定标识，计划用于精确筛选，并与 product_url 对应。 (identifier; aggregate-select; group-by; sort; aggregate-filter=eq,in; references=douyin_product_id)
- `title` — Product title recorded for the month; intended for output, not title search. / 该自然月记录的商品标题；计划用于返回展示，不用于标题搜索。 (attribute; aggregate-select; group-by; sort; requires-group-by=product_id)
- `product_url` — Douyin product-detail URL supplied by the upstream record and paired with product_id. / 抖音上游记录提供的商品详情页链接，与 product_id 对应。 (attribute; aggregate-select; group-by; sort; requires-group-by=product_id)
- `shop_id` — Stable Douyin shop identifier intended for exact filtering; a verified shop_url is not currently available. / 抖音店铺的稳定标识，计划用于精确筛选；当前没有可配套的已验证 shop_url。 (identifier; aggregate-select; group-by; sort; aggregate-filter=eq,in)
- `brand` — Brand name recorded by the upstream Douyin data; the current source does not provide a matching brand_id. / 抖音上游记录的品牌名称；当前源数据未提供与之对应的 brand_id。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains)
- `category_l1_id` — Identifier of category_l1 in the upstream Douyin category hierarchy; it may be missing. / 抖音上游品类体系中 category_l1 对应的一级品类标识；可能为空。 (identifier; aggregate-select; group-by; sort; aggregate-filter=eq,in)
- `category_l1` — Level-1 category name in the upstream Douyin hierarchy, paired with category_l1_id. / 抖音上游品类体系中的一级品类名称，与 category_l1_id 对应。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains)
- `category_l2_id` — Identifier of category_l2 in the upstream Douyin category hierarchy; it may be missing. / 抖音上游品类体系中 category_l2 对应的二级品类标识；可能为空。 (identifier; aggregate-select; group-by; sort; aggregate-filter=eq,in)
- `category_l2` — Level-2 category name in the upstream Douyin hierarchy, paired with category_l2_id. / 抖音上游品类体系中的二级品类名称，与 category_l2_id 对应。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains)
- `category_l3_id` — Identifier of category_l3 in the upstream Douyin category hierarchy; it may be missing. / 抖音上游品类体系中 category_l3 对应的三级品类标识；可能为空。 (identifier; aggregate-select; group-by; sort; aggregate-filter=eq,in)
- `category_l3` — Level-3 category name in the upstream Douyin hierarchy, paired with category_l3_id. / 抖音上游品类体系中的三级品类名称，与 category_l3_id 对应。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains)
- `category_l4_id` — Identifier of category_l4 in the upstream Douyin category hierarchy; it may be missing. / 抖音上游品类体系中 category_l4 对应的四级品类标识；可能为空。 (identifier; aggregate-select; group-by; sort; aggregate-filter=eq,in)
- `category_l4` — Level-4 category name in the upstream Douyin hierarchy, paired with category_l4_id. / 抖音上游品类体系中的四级品类名称，与 category_l4_id 对应。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains)
- `shop` — Shop name recorded by Douyin and paired with shop_id; it may change over time. / 抖音记录的店铺名称，与 shop_id 对应；名称可能随时间变化。 (dimension; aggregate-select; group-by; sort; search; aggregate-filter=eq,neq,in,not_in,contains)
- `month` — Calendar month to which the product record belongs, formatted as YYYY-MM; the public dataset grain is monthly. / 商品记录所属自然月，格式为 YYYY-MM；公开数据集为月粒度。 (time; aggregate-select; group-by; sort)
- `gmv` — Planned sales-amount metric; currency, discount treatment, and source-snapshot aggregation rules must be confirmed before runtime activation. / 计划提供的销售额指标；币种、优惠处理和源快照聚合规则须在运行时启用前确认。 (measure; aggregate-select; sort)
- `units` — Planned units-sold metric; whether the source snapshot is incremental or cumulative must be confirmed before runtime activation. / 计划提供的销量指标；源快照属于增量还是累计值，须在运行时启用前确认。 (measure; aggregate-select; sort)
- `asp` — Planned weighted average selling price; its formula and currency must be confirmed before runtime activation. / 计划提供的加权平均成交价；计算公式和币种须在运行时启用前确认。 (measure; aggregate-select; sort)

## Unavailable known fields / 暂不可用字段

- `brand_id` — Required to pair with brand, but the current Douyin source does not provide a brand identifier. / 对外提供 brand 时需要配套 brand_id，但当前抖音源数据未提供品牌标识。 (`unavailable`)
- `shop_url` — Required to pair with shop_id, but the current Douyin source does not provide a verified canonical shop URL. / 对外提供 shop_id 时需要配套 shop_url，但当前抖音源数据未提供已验证的标准店铺链接。 (`unavailable`)
- `specification` — Required product specification attributes are not present in the current Douyin source. / 当前抖音源数据缺少必要的商品规格属性。 (`unavailable`)

## Query Patterns / 查询模式

- [`aggregate_drilldown`](https://docs.asklearai.com/capabilities/douyin/tasks/aggregate_drilldown) — Query a category scope, then rank products under the same filters. / 先查询品类汇总，再在相同筛选条件下对商品排名。
- [`brand_share`](https://docs.asklearai.com/capabilities/douyin/tasks/brand_share) — Compute brand share from two atomic GMV results. / 通过两个原子销售额结果计算品牌份额。
- [`category_product_ranking`](https://docs.asklearai.com/capabilities/douyin/tasks/category_product_ranking) — Rank exact product IDs within a resolved category. / 在已对齐的品类内对商品 ID 排名。
- [`shop_name_performance`](https://docs.asklearai.com/capabilities/douyin/tasks/shop_name_performance) — Resolve a shop name and query monthly metrics. / 对齐店铺名并查询月度指标。

## Limitations / 限制

- Data is partitioned by calendar month. / 数据按自然月分区
- Product filtering supports exact product_id only; names, aliases, product URLs, and fuzzy search are not supported. / 商品筛选仅支持精确 product_id，不支持名称、别名、商品链接或模糊搜索
- Shops accept an exact shop_id or a shop name aligned with search_values. / 店铺可使用精确 shop_id 或经 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. / 同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算
- Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation. / 指标口径、覆盖量级、更新时间和访问授权仍待上游确认
- The current release contains only the first four days of 2026-06 and is incomplete. / 当前仅含 2026-06 前四天数据，数据不完整