获取秒级表现数据
您可以使用本接口获取广告的秒级表现数据，或视频素材的视频洞察数据。
欲了解视频洞察数据的用途，请查看创意素材表现数据-视频洞察数据。
注意
- 通常一只广告视频的长度不超过60秒，并且60秒内的视频效果最佳，因此我们只提供视频前60秒的数据。如果视频长度超过60秒，此时视频一般为Pangle版位投放的视频，所有60秒之后的数据会被归因（累计）到第60秒。 - 通过本接口返回的所有数据都有1小时的延迟。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径|/v1.2/reports/video_performance/get/|/v1.3/report/video_performance/get/|
|请求参数名称|order_field<br>order_type|sort_field<br>sort_type|
|请求参数类型|advertiser_id: number <br>ad_ids(位于filtering下): number[] <br>adgroup_ids(位于filtering下): number[] <br>campaign_ids(位于filtering下): number[] |advertiser_id: string <br>ad_ids(位于filtering下): string[] <br>adgroup_ids(位于filtering下): string[] <br>campaign_ids(位于filtering下): string[] |
|新增请求参数|/|report_type<br>material_ids<br>video_ids<br>start_time<br>end_time<br>lifetime|
|返回参数名称|second(位于info下)|duration(位于info下)|
|返回参数类型|ad_id(位于info下): number|ad_id(位于info下): string|
|新增指标|/|clicks<br>conversions<br>drop_off<br>retain<br>ctr<br>cvr`|
## 支持指标
```xtable
| 报表类型<br>(<code>report_type</code>) {20%}| 指标 {20%}| 数据类型 {15%} | 描述 {55%} |
|---|---|---|---|
| `AD` | `view_count` | number[] | 该广告在这一秒内的浏览量。 |
| `AD` | `click_count` | number[] | 该广告在这一秒内的点击量。 |
| `AD` | `slide_count` | number[] | 该广告的受众在这一秒内从广告滑动到主页的次数。 |
| `AD` | `convert_count` | number[] | 该广告的受众在这一秒内完成的转化事件数。 |
| `AD` | `break_count` | number[] | 在这一秒内停止观看该广告的观众数。 |
| `AD` | `like_count` | number[] | 该广告在这一秒内获得的点赞数。 |
| `AD` | `share_count` | number[] | 该广告在这一秒内获得的分享数。 |
| `AD` | `comment_count` | number[] | 该广告在这一秒内获得的评论数。 |
| `VIDEO` | `clicks`| integer[] | 该视频在这一秒内获得的点击次数。 |
| `VIDEO` | `conversions`| integer[] | 该视频在这一秒内完成的转化事件数。 |
| `VIDEO` | `drop_off` | integer[] | 在这一秒内停止观看该视频的观众数。 |
| `VIDEO` | `retain` | integer[] | 在这一秒内继续观看该视频的观众数。 |
| `VIDEO` | `ctr` | number[] | 在这一秒内视频观看产生了点击的次数占比。 |
| `VIDEO` | `cvr` | number[] | 在这一秒内视频点击产生了转化的次数占比。 |
请求
地址 https://business-api.tiktok.com/open_api/v1.3/report/video_performance/get/
方法 GET
Header
|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
参数
|字段{25%}|类型{15%}|描述{60%}|
|---|---|---|
|advertiser_id {必填}|string| 广告主ID。 |
| report_type | string | 报表类型。<br>枚举值：<ul><li> `AD`<span style="color:red">即将废弃</span>：提供广告秒级表现数据的报表。</li><li>`VIDEO`：视频素材的视频洞察报表。</li></ul>默认值：`AD`。<br><br><p><span style="color:darkred"><b>注意</b></span>：下个版本中将废弃枚举值 `AD` ，建议您使用 `VIDEO` 拉取对应报表数据。|
|metrics_fields|string[]|您想获取的指标。<br>默认返回所指定的 `report_type` 下支持的所有指标。<br>支持的指标可参见上文<b>支持指标</b>表格。|
|filtering {必填}|object| 筛选条件。<ul><li>若 `report_type` 设置为`AD`或未传入，需传入`ad_ids`，`adgroup_ids`，和 `campaign_ids`其中之一。</li><li>若`report_type`设置为`VIDEO`，需传入`material_ids` 或`video_ids`。</li></ul>|
#|ad_ids{+条件必填} |string[]|若`report_type`设置为`AD`或未传入，需传入`ad_ids` ，`adgroup_ids`，和 `campaign_ids` 其中之一。<br>您想获取对应秒级表现数据的广告ID列表。<br><p><span style="color:darkred"><b>注意</b></span>：目前，传入的`ad_ids`数量不能超过200。|
#|adgroup_ids{+条件必填} |string[]| 若`report_type`设置为`AD`或未传入，需传入`ad_ids` ，`adgroup_ids`，和 `campaign_ids` 其中之一。<br>您想获取对应秒级表现数据的广告组ID列表。|
#|campaign_ids{+条件必填} |string[]|若`report_type`设置为`AD`或未传入，需传入`ad_ids` ，`adgroup_ids`，和 `campaign_ids` 其中之一。<br>您想获取对应秒级表现数据的推广系列ID列表。|
#|material_ids{+条件必填}|string[]|若`report_type`设置为`VIDEO`，需传入`material_ids`或`video_ids`。<br>您想获取对应视频洞察数据的视频素材ID列表。<br>最大数量：1。|
#|video_ids{+条件必填}|string[]|若`report_type`设置为`VIDEO`，需传入`material_ids`或`video_ids`。<br>您想获取对应视频洞察数据的视频ID列表。<br>最大数量：1。|
#|start_time|string|仅当`report_type`设置为`VIDEO`时生效。<br>若您想获取指定时间区间的视频洞察数据，您需同时传入`start_time`和`end_time`，并将`lifetime`设置为`false`。<br>查询起始时间（闭区间），格式为`YYYY-MM-DD hh:mm:ss` (UTC+0时间)。|
#|end_time|string|仅当`report_type`设置为`VIDEO`时生效。<br>若您想获取指定时间区间的视频洞察数据，您需同时传入`start_time`和`end_time`，并将`lifetime`设置为`false`。<br>查询结束时间（闭区间），格式为`YYYY-MM-DD hh:mm:ss` (UTC+0时间)。|
#|lifetime|boolean|仅当`report_type`设置为`VIDEO`时生效。<br>若您想获取指定时间区间的视频洞察数据，您需同时传入`start_time`和`end_time`，并将`lifetime`设置为`false`。<br>是否请求指标的Lifetime（所有）数据。<br>默认值：`true`。|
|sort_field|string| 排序依据的字段。默认根据创建时间(`CREATE_TIME`)排序。|
|sort_type|string|排序类型。枚举值: `ASC` (升序，从最早创建的开始), `DES` (降序，从最晚创建的开始)。|
|page|number|页数。默认值：1。|
|page_size|number| 页面大小。取值范围：1-500。默认值：10。|
示例
(code Request http)
curl --location -g --request GET 'https://business-api.tiktok.com/open_api/v1.3/report/video_performance/get/?filtering={"ad_ids":[<ad_id>]}&advertiser_id=<advertiser_id>' \
--header 'Access-Token: <ACCESS-TOKEN>'
(/code)
返回
|字段|类型|描述|
|---|---|---|
|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|数据列表。|
##|info|object|获取数据的对象信息。|
###|ad_id|string|广告 ID。|
###|video_id|string|视频 ID。|
###|duration|number|视频时长，以秒计。|
##|metrics|object|指标与相应的值。|
###|metric_name|number[]| 指标以及顺序排列的从第0秒开始的每秒的值。<br>例如，`"share_count": [0, 0, 0, 1]`代表该广告在前两秒未被分享，在第三秒被分享了一次。<br>支持的指标可参见上文<b>支持指标</b>表格。|
#|page_info|object|分页信息。|
##|page|number|当前页码。|
##|total_page|number|总页数。|
##|page_size|number|页面大小。默认值：10。|
##|total_number|number|总结果数。|
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "202112091214160102452460391351BB20",
"data": {
"list": [
{
"info": {
"video_id": "123425gc0000c695b6bc77u1sho1s8g0",
"ad_id": "1234647413898242",
"duration": 18
},
"metrics": {
"slide_count": [
21,
7,
11,
2,
2,
1,
2,
0,
1,
0,
0,
1,
1,
0,
0,
0,
0,
0
],
"share_count": [
0,
0,
1,
0,
0,
0,
0,
0,
1,
0,
0,
0,
1,
0,
0,
0,
0,
0
],
"comment_count": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"convert_count": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"click_count": [
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0,
0
],
"view_count": [
19570,
14410,
6749,
4791,
3707,
2841,
2415,
1985,
1484,
1119,
858,
738,
658,
579,
505,
417,
311,
218
],
"break_count": [
5160,
7661,
1958,
1084,
866,
426,
430,
501,
365,
261,
120,
80,
79,
74,
88,
106,
93,
92
],
"like_count": [
65,
3567,
3981,
972,
413,
173,
140,
80,
86,
58,
26,
25,
14,
16,
14,
7,
14,
9
]
}
}
],
"page_info": {
"page": 1,
"total_page": 1,
"page_size": 10,
"total_number": 1
}
}
}
(/code);