生成 GMV Max 推广系列报表
您可以使用本接口生成 GMV Max 推广系列报表。
注意
默认返回未删除的推广系列。
频次限制
本接口的频次限制取决于您的开发者应用的频次限制等级。查看频控规则详情。
| 频次限制等级 {20%} | 每秒查询次数（QPS）{25%} | 每分钟查询次数（QPM）{25%} | 每天查询次数（QPD）{30%} |
|--- |--- |--- |--- |
| 初级 | 8 | 240 | 20,000 |
| 标准级 | 12 | 360 | 30,000 |
| 高级 | 20 | 600 | 50,000 |
| 合作级 | 20 | 600 | 50,000 |
使用前需知
您需确保对于请求的 GMV Max 推广系列类型及指标层级拥有必要的权限。请查看商品 GMV Max 推广系列或直播 GMV Max 推广系列的前提条件，确认您拥有这些权限。
请求
地址 https://business-api.tiktok.com/open_api/v1.3/gmv_max/report/get/
方法 GET
Header
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。<br>可以通过[获取访问令牌](1738373164380162.html)接口获取。|
参数
|字段{30%}|数据类型{15%}|描述{55%}|
|--- |--- |--- |
| advertiser_id {必填} | string | 广告主 ID。 |
| store_ids {必填} | string[] | TikTok Shop ID 列表。<br><br>最大数量：1。<br><br>若想获取可用于 GMV Max 推广系列的 TikTok Shop，可使用 [/gmv_max/store/list/](1822001044479041.html) 并确认返回的 `is_gmv_max_available` 为 `true`。 |
| start_date {必填} | string | 查询起始日期（闭区间），格式为 `YYYY-MM-DD`。日期基于广告账户时区。<br><br>示例：`2025-01-01`。 |
| end_date {必填} | string | 查询终止日期（闭区间），格式为 `YYYY-MM-DD`。日期基于广告账户时区。<br><br>示例：`2025-02-01`。<br><br><ul><li>若 `dimensions` 字段值不包含 `stat_time_day` 和 `stat_time_hour`，则通过 `start_date` 和 `end_date` 指定的时间区间最大为 <b>365</b> 天。</li><li> 若 `dimensions` 字段值包含 `stat_time_day`，则通过 `start_date` 和 `end_date` 指定的时间区间最大为 <b>30</b> 天。</li><li>若 `dimensions` 字段值包含 `stat_time_hour`，则通过 `start_date` 和 `end_date` 指定的时间区间最大为 <b>1</b> 天。</li></ul> |
| metrics {必填} | string[] | 要查询的指标。<br><br>若想了解可为所有 GMV Max 推广系列、商品 GMV Max 推广系列和直播 GMV Max 推广系列分别请求的指标类型，可查看 [GMV Max 推广系列报表指标](1824722485971009.html)。 |
| enable_total_metrics | boolean | 是否开启所请求指标的汇总数据。<br><br>当启用 `enable_total_metrics` 时，我们将在您查询不同页面时提供所有页面的汇总数据。<br><br>支持的值：`true`，`false`。<br>默认值：`false`。 |
| dimensions {必填} | string[] | 维度组合，用于对结果进行分组。<br><br>枚举值：<ul><li>`advertiser_id`：按广告主 ID 分组。</li><li>`campaign_id`：按推广系列 ID 分组。</li><li>`stat_time_day`：按天分组。</li><li>`stat_time_hour`：按小时分组。</li><li>`item_group_id`：按 SPU ID 分组。</li><li>`item_id`：按帖子 ID 分组。</li><li>`room_id`：按直播间 ID 分组。</li><li>`duration`：按时长分组。</li></ul><br>例如，`["campaign_id", "stat_time_day"]` 表示组合 `campaign_id` 和 `stat_time_day` （天）维度。<br><br>可用的维度组合取决于您想查询的指标类型。若想了解您想请求的指标类型支持的维度组合，可查看 [GMV Max 推广系列报表指标](1824722485971009.html)。 |
| filtering | object | 筛选条件。<br><br>若想了解您想请求的指标类型支持的筛选条件，可查看 [GMV Max 推广系列报表指标](1824722485971009.html)。 |
#| gmv_max_promotion_types | string[] | 按 GMV Max 推广系列类型筛选。<br><br>枚举值：<ul><li>`PRODUCT`：商品 GMV Max 推广系列。</li><li>`LIVE`：直播 GMV Max 推广系列。</li></ul>
#| campaign_ids | string[] | 按 GMV Max 推广系列 ID 列表筛选。<br><br>最大数量：100。 |
#| campaign_name | string | 按 GMV Max 推广系列名称筛选。<br><br>支持模糊搜索。 |
#| campaign_statuses | string[] | 按推广系列状态筛选。<br><br>枚举值：<ul><li>`STATUS_DELIVERY_OK`：投放中。</li><li>`STATUS_DISABLE`：已暂停。</li><li>`STATUS_DELETE`：已删除。</li><li>`STATUS_NOT_DELIVERY`：未投放。</li><li>`STATUS_ALL`：全部状态。</li></ul> <br><p><span style="color:darkred"><b>注意</b></span>：默认返回未删除的推广系列。|
#| item_group_ids | string[] | 按商品 SPU ID 列表筛选。<br><br>最大数量：100。 |
#| creative_types {-即将废弃}| string[] | <ul><li>使用 `campaign_ids` 和 `item_group_ids` 筛选单个 SPU ID 时必填。</li><li>在 `campaign_ids` 或 `item_group_ids` 中指定多个 ID，或同时指定多个 ID 维度时不支持本字段。</li></ul><br>按创意类型筛选。<br><br>枚举值：<ul><li>`ADS_AND_ORGANIC`：广告和原生。此类型包含已获授权并用于广告的所有创意素材。此类型中视频的总收入包括广告和原生视频产生的销售额。</li><li>`ORGANIC`：仅原生。此类型包含仅用于自然流量的视频。此类型中视频的总收入仅包括原生视频产生的销售额。</li><li>`REMOVED`：已移除。此类型包含自动选择的、但已从您的推广系列中手动移除的视频。</li></ul><br>最大数量：1。 |
#|creative_delivery_statuses|string[]|<ul><li>仅支持在以下任一场景中使用此筛选条件：<ul><li>在筛选条件 `campaign_ids` 或 `item_group_ids` 或 `campaign_ids` 和 `item_group_ids` 中指定多个 ID 时</li><li>在筛选条件 `campaign_ids` 或 `item_group_ids` 或 `campaign_ids` 和 `item_group_ids` 中指定一个 ID 时</li><li>同时指定多个 ID 维度时</li></ul></li><li>此筛选条件不可与 `creative_types` 一起使用。</li></ul><br>按创意状态筛选。<br><br>枚举值： <ul><li>`IN_QUEUE`：排队中。作品已准备好进行转化驱动潜力测试。</li><li>`LEARNING`：学习中。作品正在接受转化驱动潜力测试。</li><li>`DELIVERING`：投放中。作品已作为推广系列的一部分进行定期推广。</li><li>`NOT_DELIVERYING`：未投放。作品在测试过程中未表现出强大的转化潜力，不会作为广告计划的一部分进行定期推广。</li><li>`AUTHORIZATION_NEEDED`：需要授权。此视频尚未被授权用于广告。您可以从 TikTok 账号授权自己的视频，或向其他达人申请授权。在授权后 20 分钟内，此处的状态将会更新。</li><li>`EXCLUDED`：已排除。作品已被手动删除，无法作为广告计划的一部分进行定期推广。您可以随时将此作品重新添加到你的广告计划中。</li><li>`UNAVAILABLE`：不可用。私密视频、被拒视频、已删除视频或来自已禁用 TikTok 账号的视频不能用于广告。在某些情况下，您可能会看到来自不可用视频的消耗，这是因为在推广系列投放期间被 TikTok 内容审核流程拒绝的视频仍可能会投放一段时间。</li><li>`REJECTED`：拒绝。视频已被内容审查团队拒绝。如果您已提交申诉，那么在申诉审核完成前，视频状态将保持为“已拒绝”。</li><li>`NOT_ACTIVE`：不活跃。此视频已被降级处理，因为它上传超过 30 天且近 30 天内未产生任何收入。</li></ul> |
#| search_word | string | 按搜索关键词筛选，例如视频标题、TikTok 帖子 ID 或 TikTok 账号名称。<br><br>支持模糊搜索。 |
#| room_ids | string[] | 按直播间 ID 列表筛选。<br><br>最大数量：100。 |
| sort_field | string | 排序字段。<br><br>默认不进行排序。<br><br>推荐您使用排序字段，确保结果按顺序返回。若想查看可选的字段，可查看<a href="#item-link-支持的排序字段">支持的排序字段</a>。 |
| sort_type | string | 排序方式。<br><br>枚举值：`ASC`（升序）， `DESC`（降序）。<br>默认值：`DESC`。 |
| page | integer | 当前页数。<br><br>取值范围：≥1。<br>默认值：1。 |
| page_size | integer | 分页大小。<br><br>取值范围：1-1,000。<br>默认值：10。 |
示例
(code curl http)
curl --location --request GET https://haapi.byteintl.net/open_api/v1.3/gmv_max/report/get/?advertiser_id={{advertiser_id}}&store_ids=["{{store_id}}"]&start_date=2025-07-03&end_date=2025-07-03&metrics=["creative_delivery_status","cost","orders","cost_per_order","gross_revenue","roi","product_impressions","product_clicks","product_click_rate","ad_click_rate","ad_conversion_rate","ad_video_view_rate_2s","ad_video_view_rate_6s","ad_video_view_rate_p25","ad_video_view_rate_p50","ad_video_view_rate_p75","ad_video_view_rate_p100"]&dimensions=["item_id"]&filtering={"campaign_ids":["{{campaign_id}}"],"item_group_ids":["{{item_group_id_1}}","{{item_group_id_2}}"]}&page=1&page_size=1000
--header 'X-Use-ppe: 1' \
--header 'Access-Token: {{Access-Token}}' \
--header 'X-Tt-Env: ppe_mapi_batch' \
--header 'Content-Type: application/json' \
--header 'X-Debug-RefreshConfig: 1' \
--header 'haapi-v2: 1'
(/code)
支持的排序字段
下列表格列出了商品 GMV Max 推广系列和直播 GMV Max 推广系列分别支持的排序字段。
对于商品 GMV Max 推广系列
|字段{30%}|描述{70%}|
|---|---|
| cost | 成本 |
| net_cost | 净成本 |
| orders | 订单数（SKU） |
| cost_per_order | 平均下单成本 |
| gross_revenue | 总收入 |
| roi | ROI |
| product_impressions | 商品广告曝光数 |
| product_clicks | 商品广告点击数 |
| product_click_rate | 商品广告点击率 |
| ad_click_rate | 广告点击率 |
| ad_conversion_rate | 广告转化率 |
| ad_video_view_rate_2s | 广告视频播放达 2 秒播放率 |
| ad_video_view_rate_6s | 广告视频播放达 6 秒播放率 |
| ad_video_view_rate_p25 | 广告视频播放达 25% 播放率 |
| ad_video_view_rate_p50 | 广告视频播放达 50% 播放率 |
| ad_video_view_rate_p75 | 广告视频播放达 75% 播放率 |
| ad_video_view_rate_p100 | 广告视频播放达 100% 播放率 |
对于直播 GMV Max 推广系列
|字段{30%}|描述{70%}|
|---|---|
| cost | 成本 |
| net_cost | 净成本 |
| orders | 订单数 |
| cost_per_order | 平均下单成本 |
| gross_revenue | 总收入 |
| roi | ROI |
| live_views | 直播播放量 |
| cost_per_live_view | 直播播放平均成本 |
| 10_second_live_views | 直播播放达 10 秒播放量 |
| cost_per_10_second_live_view | 直播播放达 10 秒平均成本 |
| live_follows | 直播关注数 |
示例
若想获取用于生成 GMV Max 推广系列报表的详尽代码示例，可查看 GMV Max 推广系列报表指标。
返回
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code|number|返回码。完整返回码列表及描述参见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message|string|返回信息。更多信息参见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|request_id|string|请求的日志 ID，唯一标识一个请求。|
|data|object|返回数据。|
#|total_metrics|object|仅当请求中 `enable_total_metrics` 设置为 `true` 时返回本字段。<br><br>所请求指标的汇总数据。|
##|{metric_name}|string|返回的指标，取决于请求中的指定的 `metrics` 字段。|
#|list|object[]|数据列表。|
##|dimensions|object|所请求的维度数据。|
###|{dimension_name}|string|返回的维度，取决于请求中的指定的 `dimensions` 字段。|
##|metrics|object|所请求的指标数据。|
###|{metric_name}|string|返回的指标，取决于请求中的指定的 `metrics` 字段。|
#|page_info|object|分页信息。|
##|page|integer|当前页数。|
##|page_size|integer|分页大小。|
##|total_number|integer|总结果数。|
##|total_page|integer|总页数。|
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"list": [
{
"dimensions": {
"item_id": "{{item_id}}"
},
"metrics": {
"ad_click_rate": "16.67",
"ad_conversion_rate": "0.00",
"ad_video_view_rate_2s": "40.00",
"ad_video_view_rate_6s": "40.00",
"ad_video_view_rate_p100": "20.00",
"ad_video_view_rate_p25": "40.00",
"ad_video_view_rate_p50": "20.00",
"ad_video_view_rate_p75": "20.00",
"cost": "0.01",
"cost_per_order": "0.00",
"creative_delivery_status": "UNAVAILABLE",
"currency": "USD",
"gross_revenue": "0.00",
"orders": "0",
"product_click_rate": "16.67",
"product_clicks": "1",
"product_impressions": "6",
"roi": "0.00"
}
},
{
"dimensions": {
"item_id": "{{item_id}}"
},
"metrics": {
"ad_click_rate": "0.00",
"ad_conversion_rate": "0.00",
"ad_video_view_rate_2s": "0.00",
"ad_video_view_rate_6s": "0.00",
"ad_video_view_rate_p100": "0.00",
"ad_video_view_rate_p25": "0.00",
"ad_video_view_rate_p50": "0.00",
"ad_video_view_rate_p75": "0.00",
"cost": "0.00",
"cost_per_order": "0.00",
"creative_delivery_status": "UNAVAILABLE",
"currency": "USD",
"gross_revenue": "0.00",
"orders": "0",
"product_click_rate": "0.00",
"product_clicks": "0",
"product_impressions": "0",
"roi": "0.00"
}
}
],
"page_info": {
"page": 1,
"page_size": 1000,
"total_number": 246,
"total_page": 1
}
}
}
(/code)