← 返回目录
📁 API Reference › Creative Reports

视频洞察报表

请求视频洞察报表

您可以使用本接口请求视频洞察报表，获取单个或多个广告账户中多个视频的表现数据，包括 Spark Ads 和非 Spark Ads 广告中视频的数据。

请求

地址 https://business-api.tiktok.com/open_api/v1.3/creative/report/get/

方法 GET

Header

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|

参数

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
| report_type {必填} | string | 报表类型。<br><br>枚举值： <ul><li>`VIDEO_INSIGHT`：为一个或多个广告账号生成的视频洞察报表。</li></ul>|
| advertiser_id {+条件必填} | string | 需传入 `advertiser_id` 和 `advertiser_ids` 其中之一。<br><br>单个广告主 ID，用于为该广告主生成报表。 |
| advertiser_ids {+条件必填} | string[] | 需传入 `advertiser_id` 和 `advertiser_ids` 其中之一。 <br><br>广告主 ID 列表，用于为列表中的所有广告主生成报表。 <br><br>最大数量：50。<br><br> <br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>您需对列表对应的所有广告账号均有访问权限。若想获取某一商务中心中您有访问权限的广告账号，可使用[/bc/asset/get/](1739432717798401.html)。</li><li>若广告账号的币种不同，则返回的指标默认币种为美元。 </li></ul>  |
| start_date{必填} | string | 查询起始日期（闭区间），格式为`YYYY-MM-DD`（UTC + 0 时间）。 <br><br> 示例：`2024-01-01`。<br><br>`start_date` 和 `end_date` 定义的最大查询时间区间为 365 天。 |
| end_date {必填} | string | 查询结束日期（闭区间），格式为`YYYY-MM-DD`（UTC + 0 时间）。 <br><br> 示例：`2024-01-01`。<br><br>`start_date` 和 `end_date` 定义的最大查询时间区间为 365 天。 |
| metrics_fields | string[] | 您想要查询数据的指标。<ul><li>若未传入本字段，将默认返回视频洞察报表中支持的所有指标。</li><li>若想了解支持的指标，请查看[视频洞察报表中支持的指标](1789703614085122.html)。 </li></ul> |
| filtering | object | 筛选条件。 |
#| material_id | string[] | 视频素材 ID 列表。<br><br>最大数量：20。<br><br>若想获取视频的素材 ID，可使用[/file/video/ad/search/](1740050472224769.html)。 |
#| material_name | string | 视频素材名称。<br><br>支持模糊搜索。 |
#| tiktok_item_ids | string[] | TikTok Spark Ads 帖子的 ID 列表，用于筛选用于创建这些帖子的视频。<br><br>最大数量：20。<br><br>若想获取 TikTok 帖子 ID，可使用 [/tt_video/info/](1738376324021250.html) 或 [/identity/video/get/](1740218475032577.html)。 |
#| country_code | string[] | 地区代码列表，用于筛选在这些地区投放的视频。 <br><br>若想了解枚举值，请查看[附录 - 地区代码](1737585867307010.html)。 |
#| creative_formats | string[] | 素材样式列表。<br><br>枚举值： <ul><li> `VIDEO_16_9`：视频（16：9）。</li><li>`VIDEO_1_1`：视频（1：1）。</li><li>`VIDEO_9_16`：视频（9：16）。</li><li>`OTHER`：其他。</li></ul>|
#| video_material_sources | string[] | 视频素材来源列表。<br><br>枚举值：<ul><li>`UPLOADED_TO_TIKTOK_ADS_MANAGER`：上传至 TikTok 广告管理平台的视频。 </li><li> `UPLOADED_TO_CATALOG`：上传至商品库的视频。</li><li> `CREATIVE_TOOL_SMART_VIDEO`：创意工具 - 微电影。</li><li> `CREATIVE_TOOL_QUICK_OPTIMIZATION`：创意工具 - 一键优化。</li><li> `CREATIVE_TOOL_VIDEO_TEMPLATE`：创意工具 - 模版视频。</li><li> `CREATIVE_TOOL_SMART_VIDEO_SOUNDTRACK`：创意工具 - 智能配乐。</li><li>`CREATIVE_TOOL_TIKTOK_VIDEO_EDITOR`：创意工具 - 视频编辑器。</li><li> `TIKTOK_CREATIVE_EXCHANGE`：TikTok Creative Exchange。</li><li>`CATALOG_VIDEO_TEMPLATE`：商品库视频模版。 </li><li> `DYNAMIC_VIDEO_EDITOR`：动态视频编辑器。</li><li> `CREATIVE_CHALLENGE`：创意挑战。</li><li>`AUTOMATED_CREATIVE_OPTIMIZATION`：程序化创意。</li><li>`OTHER`：其他。</li><li>`QUICK_GENERATION`：快速生成。</li><li> `CREATIVE_CENTER_VIDEO_UPLOAD`：创意中心 - 视频上传。</li><li>`CREATIVE_CENTER_TIKTOK_VIDEO_EDITOR`：创意中心 - TikTok 视频编辑器。</li><li> `CREATIVE_CENTER_VIDEO_TEMPLATE`：创意中心 - 视频模板。</li><li>`DYNAMIC_SCENE`：动态场景。</li><li>`SMART_OPTIMIZATION_TOOL`：智能优化工具。</li></ul>  |
#| placement | string[] | 广告版位（广告位）列表。<br><br>枚举值：<ul><li>`PLACEMENT_TIKTOK`：TikTok。</li><li>`PLACEMENT_PANGLE`：Pangle。</li><li> `PLACEMENT_GLOBAL_APP_BUNDLE`：全球化应用组合。</li></ul>|
#| identities | string[] | 认证身份（广告发布身份）列表。<br><br>枚举值：<ul><li>`SPARK_ADS`：可用于 Spark Ads 的认证身份，包括授权用户、TikTok 用户 和添加到商务中心的 TikTok 用户身份。</li><li>`NON_SPARK_ADS`：不可用于 Spark Ads 的认证身份，即自定义用户身份。</li></ul><br>若想了解认证身份详情，请查看[认证身份](1738958351620097.html)。 |
#| ad_name | string | 广告名称。<br><br>支持模糊搜索。 |
#| ad_id | string[] | 广告 ID 列表。<br><br>最大数量：20。 |
#| adgroup_name | string | 广告组名称。<br><br>支持模糊搜索。 |
#| adgroup_id | string[] | 广告组 ID 列表。 <br><br>最大数量：20。 |
#| campaign_name | string | 推广系列名称。<br><br>支持模糊搜索。 |
#| campaign_id | string[] | 推广系列 ID 列表。 <br><br>最大数量：20。 |
| sort_field | string | 排序字段。<br><br>若想了解可用于排序的字段，请查看[视频洞察报表中支持的指标](1789703614085122.html)。 |
| sort_type | string | 排序方式。<br><br>枚举值：`ASC`（升序）, `DESC`（降序）。<br>默认值：`DESC`。 |
| page | number | 当前页数。<br><br>默认值：1。<br>取值范围：≥ 1。 |
| page_size | number | 分页大小。<br><br>默认值：10。<br>取值范围：1-1,000。 |

示例

(code curl http)
curl --location --request GET'https://business-api.tiktok.com/open_api/v1.3/creative/report/get/?report_type=VIDEO_INSIGHT&advertiser_id={{advertiser_id}}&start_date=2023-12-24&end_date=2024-01-23' \
--header 'Access-Token: {{Access-Token}}' \
(/code)

返回

|字段{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| 返回数据。 |
#| list | object[] | 视频洞察数据。 <br> <br><p><span style="color:darkred"><b>注意</b></span>：默认仅返回总消耗（`spend`）大于 0 的视频数据。无消耗的视频将被筛除。 |
##| metrics | object | 视频的指标数据。<br><br><ul><li>若请求中未传入 `metrics_fields`，将默认返回视频洞察报表中支持的所有指标。若想了解支持的指标，请查看[视频洞察报表中支持的指标](1789703614085122.html)。</li><li>若请求中传入`metrics_fields`，则仅返回指定的指标的数据。</li></ul>|
##| info | object | 视频的素材信息。 |
###| material_id | string | 视频素材 ID。 |
###| material_name | string | 视频素材名称。 |
###| create_time | string | 视频创建的时间，采用 [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) 格式。 <br> <br>示例： "2024-01-01T00:00:01Z"。 |
###| tiktok_item_ids | string[] | 仅当视频（`material_id`）已用于创建 Spark Ads 时返回。<br> <br>使用该视频创建过的 TikTok Spark Ads 帖子的 ID 列表。 |
###| country_code| string[] | 视频（`material_id`）投放的地区的地区代码列表。<br> <br>若想了解枚举值，请查看[附录 - 地区代码](https://ads.tiktok.com/marketing_api/docs?id=1737585867307010)。 |
###| video_material_source | string | 视频素材来源。<br><br>枚举值：<ul><li>`UPLOADED_TO_TIKTOK_ADS_MANAGER`：上传至 TikTok 广告管理平台的视频。 </li><li> `UPLOADED_TO_CATALOG`：上传至商品库的视频。</li><li> `CREATIVE_TOOL_SMART_VIDEO`：创意工具 - 微电影。</li><li> `CREATIVE_TOOL_QUICK_OPTIMIZATION`：创意工具 - 一键优化。</li><li> `CREATIVE_TOOL_VIDEO_TEMPLATE`：创意工具 - 模版视频。</li><li> `CREATIVE_TOOL_SMART_VIDEO_SOUNDTRACK`：创意工具 - 智能配乐。</li><li>`CREATIVE_TOOL_TIKTOK_VIDEO_EDITOR`：创意工具 - 视频编辑器。</li><li> `TIKTOK_CREATIVE_EXCHANGE`：TikTok Creative Exchange。</li><li>`CATALOG_VIDEO_TEMPLATE`：商品库视频模版。 </li><li> `DYNAMIC_VIDEO_EDITOR`：动态视频编辑器。</li><li> `CREATIVE_CHALLENGE`：创意挑战。</li><li>`AUTOMATED_CREATIVE_OPTIMIZATION`：程序化创意。</li><li>`OTHER`：其他。</li><li>`QUICK_GENERATION`：快速生成。</li><li> `CREATIVE_CENTER_VIDEO_UPLOAD`：创意中心 - 视频上传。</li><li>`CREATIVE_CENTER_TIKTOK_VIDEO_EDITOR`：创意中心 - TikTok 视频编辑器。</li><li> `CREATIVE_CENTER_VIDEO_TEMPLATE`：创意中心 - 视频模板。</li><li>`DYNAMIC_SCENE`：动态场景。</li><li>`SMART_OPTIMIZATION_TOOL`：智能优化工具。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：若视频的素材来源无法追踪，本字段可能返回 null 值。 |
###| placement | string[] | 视频投放的广告版位。<br><br>枚举值：<ul><li>`PLACEMENT_TIKTOK`：TikTok。</li><li>`PLACEMENT_PANGLE`：Pangle。</li><li> `PLACEMENT_GLOBAL_APP_BUNDLE`：全球化应用组合。</li></ul> |
###| identity | string | 视频投放时使用的认证身份。<br><br>枚举值：<ul><li>`SPARK_ADS`：可用于 Spark Ads 的认证身份，包括授权用户、TikTok 用户 和添加到商务中心的 TikTok 用户身份。</li><li>`NON_SPARK_ADS`：不可用于 Spark Ads 的认证身份，即自定义用户身份。</li></ul><br>若想了解认证身份详情，请查看[认证身份](1738958351620097.html)。  |
###| currency | string | `metrics` 中的指标数据使用的币种代码。<br><br>示例：USD。<br><br>若想了解币种代码对应的币种，请查看[不同币种的预算校验比例和取值范围](1737585839634433.html)。 |

示例

(code Success-Response http)
HTTPS/1.1 200 OK

{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "list": [
            {
                "metrics": {
                    "impressions": "63727",
                    "cpm": "10.27",
                    "ctr": "0.38",
                    "organic_video_views": null,
                    "clicks": "243",
                    "cpc": "2.69",
                    "spend": "654.39",
                    "conversion_rate_v2": "0.01",
                    "conversion": "6",
                    "cost_per_conversion": "109.07"
                },
                "info": {
                    "material_name": "{{material_name}}",
                    "identity": "NON_SPARK_ADS",
                    "placement": [
                        "PLACEMENT_TIKTOK"
                    ],
                    "video_material_source": "UPLOADED_TO_TIKTOK_ADS_MANAGER",
                    "currency": "USD",
                    "country_code": [
                        "CA",
                        "US"
                    ],
                    "create_time": "2024-01-11T07:42:46Z",
                    "material_id": "{{material_id}}"
                }
            },
            {
                "metrics": {
                    "impressions": "200626",
                    "cpm": "4.62",
                    "ctr": "1.36",
                    "organic_video_views": "58242.0",
                    "clicks": "2732",
                    "cpc": "0.34",
                    "spend": "927.25",
                    "conversion_rate_v2": "0.01",
                    "conversion": "17",
                    "cost_per_conversion": "54.54"
                },
                "info": {
                    "material_name": "{{material_name}}",
                    "tiktok_item_ids": [
                        "{{tiktok_item_id}}"
                    ],
                    "identity": "SPARK_ADS",
                    "placement": [
                        "PLACEMENT_TIKTOK"
                    ],
                    "video_material_source": null,
                    "currency": "USD",
                    "country_code": [
                        "CA",
                        "US"
                    ],
                    "create_time": "2023-09-25T08:47:43Z",
                    "material_id": "{{material_id}}"
                }
            }
        ],
        "page_info": {
            "total_number": 2,
            "total_page": 1,
            "page_size": 10,
            "page": 1
        }
    }
}
(/code)
← 创意报表视频洞察报表中支持的指标 →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →