---
title: "获取广告互动分析/Get ad interactive analysis"
method: POST
path: "/api/v1/tiktok/ads/get_ad_interactive_analysis"
tags: ["TikTok-Ads-API"]
---

# 获取广告互动分析/Get ad interactive analysis

`POST /api/v1/tiktok/ads/get_ad_interactive_analysis`

## Request

- Base URL: `https://api.tikhub.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tikhub.io/api/v1/tiktok/ads/get_ad_interactive_analysis`
- Auth: HTTP bearer

# [中文]
### 用途:
- 获取广告的互动时间分析，了解观众在视频不同时间点的留存和互动情况
- 分析广告视频的吸引力曲线，找出最佳时长和关键互动点
- 优化广告内容结构，提高整体效果

### 参数:
- material_id: 广告素材ID，必填参数
- metric_type: 分析类型
    - ctr: 点击率分析
    - cvr: 转化率分析
    - clicks: 点击次数分析
    - conversion: 转化次数分析
    - remain: 留存率分析 (默认)
- period_type: 时间范围，默认180天
- cookie: 自定义Cookie字符串，可选参数，可以使用自己的Cookie来获取更多数据

### 返回内容说明:
- `interactive_data`: 互动分析数据
  - `time_series`: 时间序列数据
    - `time`: 视频播放时间点（秒）
    - `value`: 对应的指标值（如留存率）
  - `average_watch_time`: 平均观看时长
  - `completion_rate`: 完播率
  - `peak_interaction_time`: 互动高峰时间点

### 示例响应:
```json
{
  "code": 200,
  "router": "/api/v1/tiktok/ads/get_ad_interactive_analysis",
  "params": {
    "material_id": "7213258221116751874",
    "metric_type": "remain",
    "period_type": 180
  },
  "data": {
    "interactive_data": {
      "time_series": [
        {"time": 0, "value": 100},
        {"time": 1, "value": 95},
        {"time": 2, "value": 88}
      ],
      "average_watch_time": 8.5,
      "completion_rate": 65.2,
      "peak_interaction_time": 3
    }
  }
}
```

# [English]
### Purpose:
- Get ad interactive time analysis to understand audience retention and engagement at different video time points
- Analyze ad video attractiveness curve to find optimal duration and key interaction points
- Optimize ad content structure to improve overall effectiveness

### Parameters:
- material_id: Ad material ID, required parameter
- metric_type: Analysis type
    - ctr: Click-through rate analysis
    - cvr: Conversion rate analysis
    - clicks: Click count analysis
    - conversion: Conversion count analysis
    - remain: Retention rate analysis (default)
- period_type: Time range, default 180 days
- cookie: Custom Cookie string, optional parameter, can be used to fetch more data

### Return Description:
- `interactive_data`: Interactive analysis data
  - `time_series`: Time series data
    - `time`: Video playback time point (seconds)
    - `value`: Corresponding metric value (e.g., retention rate)
  - `average_watch_time`: Average watch time
  - `completion_rate`: Completion rate
  - `peak_interaction_time`: Peak interaction time point

### Example Response:
```json
{
  "code": 200,
  "router": "/api/v1/tiktok/ads/get_ad_interactive_analysis",
  "params": {
    "material_id": "7213258221116751874",
    "metric_type": "remain",
    "period_type": 180
  },
  "data": {
    "interactive_data": {
      "time_series": [
        {"time": 0, "value": 100},
        {"time": 1, "value": 95},
        {"time": 2, "value": 88}
      ],
      "average_watch_time": 8.5,
      "completion_rate": 65.2,
      "peak_interaction_time": 3
    }
  }
}
```

## Request body

- BodyGetAdInteractiveAnalysisApiV1TiktokAdsGetAdInteractiveAnalysisPost
  - `material_id` string, required: 广告素材ID/Ad material ID
  - `metric_type` string: 分析类型/Analysis type (ctr, cvr, clicks, conversion, remain)
  - `period_type` integer: 时间范围(天)/Period type (days)
  - `cookie` string: 自定义Cookie字符串（可选）

## Response `200`

Successful Response

- ResponseModel
  - `code` integer: HTTP status code | HTTP状态码
  - `request_id` string, nullable: Unique request identifier | 唯一请求标识符
  - `message` string: Response message (EN-US) | 响应消息 (English)
  - `message_zh` string: Response message (ZH-CN) | 响应消息 (中文)
  - `support` string: Support message | 支持消息
  - `time` string: The time the response was generated | 生成响应的时间
  - `time_stamp` integer: The timestamp the response was generated | 生成响应的时间戳
  - `time_zone` string: The timezone of the response time | 响应时间的时区
  - `docs` string, nullable: Link to the API Swagger documentation for this endpoint | 此端点的 API Swagger 文档链接
  - `cache_message` string, nullable: Cache message (EN-US) | 缓存消息 (English)
  - `cache_message_zh` string, nullable: Cache message (ZH-CN) | 缓存消息 (中文)
  - `cache_url` string, nullable: The URL to access the cached result | 访问缓存结果的 URL
  - `router` string: The endpoint that generated this response | 生成此响应的端点
  - `params` unknown
  - `data` unknown

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-08** `96a122a5f220`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-09-01** `50f9ec6e1cd3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/changes/api/v1/tiktok/ads/get_ad_interactive_analysis/post.md)

---

[API](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi.md) - [All operations](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/llms.txt) - [OpenAPI document](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/revisions/86a3483c705a?raw)