# 获取直播场次历史记录/Fetch live room history list ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /api/v1/douyin/creator_v2/fetch_live_room_history_list: post: summary: 获取直播场次历史记录/Fetch live room history list deprecated: false description: >- # [中文] ### 用途: - 获取抖音创作者的直播场次历史记录 - 查看指定时间范围内的所有直播场次数据 - 支持查询正在进行的直播和历史直播记录 - **此接口需要用户提供有效的抖音创作者平台Cookie** - **使用 POST 方法，Cookie 在请求体中传输，更安全** ### 请求体参数: - cookie: 用户的抖音创作者平台Cookie（必填，在请求体中传输） - start_date: 开始日期，格式为 YYYY-MM-DD（必填，例如: "2025-09-11"） - end_date: 结束日期，格式为 YYYY-MM-DD（必填，例如: "2025-10-11"） - limit: 每页数量限制，默认400，最多400条 - need_living: 是否包含正在直播的场次（0=不包含, 1=包含，默认1） - download: 是否下载（0=不下载, 1=下载，默认0） ### 返回数据说明: 返回直播场次历史记录列表，数据位于 `data.data.series` 数组中，每个场次包含以下信息： **基本信息**: - roomID: 直播间ID - roomTitle: 直播标题 - coverUri: 直播封面图片URL - startTime: 开始时间（格式: "YYYY-MM-DD HH:mm:ss"） - endTime: 结束时间（格式: "YYYY-MM-DD HH:mm:ss"） - liveDurationWithoutPause: 直播时长（不含暂停时间，格式如: "1分钟5秒"） - playStatus: 播放状态（4=已结束） **流量数据**: - watchCnt: 总观看人次 - serverWatchUcntTdDirect: 直接观看用户数（来自服务端统计） - pcu: 峰值同时在线人数（Peak Concurrent Users） - liveServerWatchDurationTdPavg: 平均观看时长 **互动数据**: - serverLikeCntTd: 点赞数 - clientCommentUcntTd: 评论用户数 - liveNewFollowUcnt: 新增关注数 **消费/转化数据**: - liveConsumeUcnt: 消费用户数 - liveFansConsumeUcntTd: 粉丝消费用户数 - roomLiveEarnScore: 直播收益积分 ### 数据价值: - **历史回顾**: 查看所有直播场次的完整记录 - **数据对比**: 对比不同场次的表现差异 - **趋势分析**: 分析直播效果的变化趋势 - **优化方向**: 找出高转化场次的共同特点 - **时间规划**: 根据历史数据优化直播时间 - **内容策略**: 根据不同主题的效果调整内容 ### 应用场景: 1. **定期复盘**: 每周/每月查看直播数据进行总结 2. **效果评估**: 评估不同时段、不同主题的直播效果 3. **数据报表**: 生成直播数据报表供团队分析 4. **策略优化**: 基于历史数据制定下一步直播策略 5. **KPI追踪**: 追踪直播相关的关键指标完成情况 6. **趋势预测**: 预测未来直播的潜在表现 ### 注意事项: 1. **时间范围**: 建议查询时间不超过3个月，避免数据量过大 2. **数量限制**: 单次最多返回400条记录 3. **数据延迟**: 直播数据可能有1-2小时的延迟 4. **正在直播**: 设置need_living=1可以查看当前正在进行的直播 5. **Cookie有效性**: 确保Cookie未过期，否则无法获取数据 6. **日期格式**: 必须使用YYYY-MM-DD格式，如2025-09-11 ### Cookie 获取方式: 1. 登录抖音创作者平台 (https://creator.douyin.com) 2. 打开浏览器开发者工具（F12） 3. 切换到 Network 标签 4. 刷新页面或进行操作 5. 找到任意请求，复制 Cookie 请求头的值 # [English] ### Purpose: - Get Douyin creator's live room history list - View all live session data within a specified time range - Support querying ongoing and historical live sessions - **This API requires users to provide valid Douyin Creator Platform Cookie** - **Use POST method, Cookie is transmitted in request body, more secure** ### Request Body Parameters: - cookie: User's Douyin Creator Platform Cookie (required, transmitted in request body) - start_date: Start date in YYYY-MM-DD format (required, e.g., "2025-09-11") - end_date: End date in YYYY-MM-DD format (required, e.g., "2025-10-11") - limit: Limit per page, default 400, max 400 - need_living: Include ongoing live sessions (0=No, 1=Yes, default 1) - download: Download flag (0=No download, 1=Download, default 0) ### Return Data Description: Returns a list of live session history, data is located in `data.data.series` array, each session includes: **Basic Info**: - roomID: Live room ID - roomTitle: Live title - coverUri: Live cover image URL - startTime: Start time (format: "YYYY-MM-DD HH:mm:ss") - endTime: End time (format: "YYYY-MM-DD HH:mm:ss") - liveDurationWithoutPause: Duration without pause (format: "1 minute 5 seconds") - playStatus: Play status (4=Ended) **Traffic Data**: - watchCnt: Total watch count - serverWatchUcntTdDirect: Direct watch user count (from server statistics) - pcu: Peak Concurrent Users - liveServerWatchDurationTdPavg: Average watch duration **Engagement Data**: - serverLikeCntTd: Likes count - clientCommentUcntTd: Comment user count - liveNewFollowUcnt: New followers count **Consumption/Conversion Data**: - liveConsumeUcnt: Consuming user count - liveFansConsumeUcntTd: Fan consuming user count - roomLiveEarnScore: Live room earn score ### Data Value: - **History Review**: View complete records of all live sessions - **Data Comparison**: Compare performance across sessions - **Trend Analysis**: Analyze changes in live performance - **Optimization**: Identify common traits of high-conversion sessions - **Time Planning**: Optimize live timing based on historical data - **Content Strategy**: Adjust content based on theme performance ### Use Cases: 1. **Regular Review**: Weekly/monthly live data summary 2. **Effect Evaluation**: Evaluate performance by time and theme 3. **Data Reports**: Generate reports for team analysis 4. **Strategy Optimization**: Develop strategies based on data 5. **KPI Tracking**: Track live-related KPIs 6. **Trend Prediction**: Predict future live performance ### Notes: 1. **Time Range**: Recommended not to exceed 3 months 2. **Quantity Limit**: Max 400 records per request 3. **Data Delay**: 1-2 hours delay possible 4. **Ongoing Live**: Set need_living=1 to include current live 5. **Cookie Validity**: Ensure Cookie is not expired 6. **Date Format**: Must use YYYY-MM-DD format ### How to get Cookie: 1. Login to Douyin Creator Platform (https://creator.douyin.com) 2. Open browser developer tools (F12) 3. Switch to Network tab 4. Refresh page or perform operations 5. Find any request and copy the Cookie header value # [示例/Example] ```json { "cookie": "Your_Cookie_Here", "start_date": "2025-09-11", "end_date": "2025-10-11", "limit": 400, "need_living": 1, "download": 0 } ``` ### 返回数据示例/Response Example: ```json { "data": { "code": 0, "componentID": "", "data": { "series": [ { "clientCommentUcntTd": "0", "coverUri": "https://p3-webcast-sign.douyinpic.com/...", "endTime": "2025-11-20 13:52:20", "liveConsumeUcnt": "1", "liveDurationWithoutPause": "1分钟5秒", "liveFansConsumeUcntTd": "1", "liveNewFollowUcnt": "0", "liveServerWatchDurationTdPavg": "0.5666666666666667", "pcu": "1", "playStatus": "4", "roomID": "75746809889xxxxxx", "roomLiveEarnScore": "1", "roomTitle": "xxxxxxxx", "serverLikeCntTd": "0", "serverWatchUcntTdDirect": "1", "startTime": "2025-11-20 13:51:15", "watchCnt": "1" } ] }, "meta": "" } } ``` ### 数据解读/Data Interpretation: - **watchCnt**: 总观看人次，反映直播的曝光度和吸引力 - **pcu**: 峰值同时在线人数（Peak Concurrent Users），反映直播的热度峰值 - **liveServerWatchDurationTdPavg**: 平均观看时长，反映内容的吸引力 - **liveNewFollowUcnt**: 新增关注数，反映直播的转粉效果 - **roomLiveEarnScore**: 直播收益积分，反映直播的收益能力 - **liveConsumeUcnt/liveFansConsumeUcntTd**: 消费用户数/粉丝消费用户数，反映直播的转化能力 - **互动率**: (serverLikeCntTd+clientCommentUcntTd)/watchCnt，反映用户活跃度 ### 优化建议/Optimization Suggestions: 1. **高峰分析**: 分析pcu最高出现的时间点，强化该时段的内容 2. **留存优化**: 提升liveServerWatchDurationTdPavg平均观看时长，增加内容的连贯性和吸引力 3. **互动引导**: 在直播中增加互动环节，提升serverLikeCntTd点赞数、clientCommentUcntTd评论数 4. **转粉策略**: 在直播中适时引导关注，提升liveNewFollowUcnt新增关注数 5. **消费转化**: 分析高roomLiveEarnScore场次的特点，优化直播策略 6. **时间选择**: 根据历史数据选择watchCnt观看人次最多的时段开播 operationId: >- fetch_live_room_history_list_api_v1_douyin_creator_v2_fetch_live_room_history_list_post tags: - Douyin-Creator-V2-API - Douyin-Creator-V2-API parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/LiveRoomHistoryListRequest' description: 直播场次历史记录请求参数/Live room history list request parameters example: cookie: Your_Cookie_Here start_date: '2025-09-11' end_date: '2025-10-11' limit: 400 need_living: 1 download: 0 responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ResponseModel' headers: {} x-apifox-name: OK '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' headers: {} x-apifox-name: Unprocessable Entity security: - HTTPBearer: [] x-apifox: schemeGroups: - id: bjwcuuaQgErBjjNkDs7Qe schemeIds: - HTTPBearer required: true use: id: bjwcuuaQgErBjjNkDs7Qe scopes: bjwcuuaQgErBjjNkDs7Qe: HTTPBearer: [] x-apifox-folder: Douyin-Creator-V2-API x-apifox-status: released x-run-in-apifox: https://app.apifox.com/web/project/4705614/apis/api-359719873-run components: schemas: LiveRoomHistoryListRequest: properties: cookie: type: string title: Cookie description: 用户Cookie/User Cookie examples: - Your_Cookie_Here start_date: type: string title: Start Date description: 开始日期(格式YYYY-MM-DD)/Start date (format YYYY-MM-DD) examples: - '2025-09-11' end_date: type: string title: End Date description: 结束日期(格式YYYY-MM-DD)/End date (format YYYY-MM-DD) examples: - '2025-10-11' limit: type: integer title: Limit description: 每页数量限制/Limit per page (最多400条) default: 400 examples: - 400 need_living: type: integer title: Need Living description: '是否包含正在直播的场次/Include living rooms: 0=不包含, 1=包含' default: 1 examples: - 1 download: type: integer title: Download description: '是否下载/Download: 0=不下载, 1=下载' default: 0 examples: - 0 type: object required: - cookie - start_date - end_date title: LiveRoomHistoryListRequest description: |- 直播场次历史记录请求模型 Live Room History List Request Model x-apifox-orders: - cookie - start_date - end_date - limit - need_living - download x-apifox-ignore-properties: [] x-apifox-folder: '' ResponseModel: properties: code: type: integer title: Code description: HTTP status code | HTTP状态码 default: 200 request_id: anyOf: - type: string - type: 'null' title: Request Id description: Unique request identifier | 唯一请求标识符 message: type: string title: Message description: Response message (EN-US) | 响应消息 (English) default: Request successful. This request will incur a charge. message_zh: type: string title: Message Zh description: Response message (ZH-CN) | 响应消息 (中文) default: 请求成功，本次请求将被计费。 support: type: string title: Support description: Support message | 支持消息 default: 'Discord: https://discord.gg/aMEAS8Xsvz' time: type: string title: Time description: The time the response was generated | 生成响应的时间 time_stamp: type: integer title: Time Stamp description: The timestamp the response was generated | 生成响应的时间戳 time_zone: type: string title: Time Zone description: The timezone of the response time | 响应时间的时区 default: America/Los_Angeles docs: anyOf: - type: string - type: 'null' title: Docs description: >- Link to the API Swagger documentation for this endpoint | 此端点的 API Swagger 文档链接 cache_message: anyOf: - type: string - type: 'null' title: Cache Message description: Cache message (EN-US) | 缓存消息 (English) default: >- This response is cached and accessible via the URL below for 24 hours at no extra cost. The cache is for request tracing only — it doesn't affect the API's data freshness and won't be returned through the API again. cache_message_zh: anyOf: - type: string - type: 'null' title: Cache Message Zh description: Cache message (ZH-CN) | 缓存消息 (中文) default: >- 本次响应已缓存，可通过下方 URL 直接查看，有效期 24 小时，访问缓存链接无额外费用。缓存仅用于请求溯源，不影响接口数据的时效性，也不会再次通过接口返回。 cache_url: anyOf: - type: string - type: 'null' title: Cache Url description: The URL to access the cached result | 访问缓存结果的 URL router: type: string title: Router description: The endpoint that generated this response | 生成此响应的端点 default: '' params: type: string data: anyOf: - type: string - type: 'null' title: Data description: The response data | 响应数据 type: object title: ResponseModel x-apifox-orders: - code - request_id - message - message_zh - support - time - time_stamp - time_zone - docs - cache_message - cache_message_zh - cache_url - router - params - data x-apifox-ignore-properties: [] x-apifox-folder: '' HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError x-apifox-orders: - detail x-apifox-ignore-properties: [] x-apifox-folder: '' ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError x-apifox-orders: - loc - msg - type x-apifox-ignore-properties: [] x-apifox-folder: '' securitySchemes: HTTPBearer: type: bearer description: > ---- #### API Token Introduction: ##### Method 1: Use API Token in the Request Header (Recommended) - **Header**: `Authorization` - **Format**: `Bearer {token}` - **Example**: `{"Authorization": "Bearer your_token"}` - **Swagger UI**: Click on the `Authorize` button in the upper right corner of the page to enter the API token directly without the `Bearer` keyword. ##### Method 2: Use API Token in the Cookie (Not Recommended, Use Only When Method 1 is Unavailable) - **Cookie**: `Authorization` - **Format**: `Bearer {token}` - **Example**: `Authorization=Bearer your_token` #### Get API Token: 1. Register and log in to your account on the TikHub website. 2. Go to the user center, click on the API token menu, and create an API token. 3. Copy and use the API token in the request header. 4. Keep your API token confidential and use it only in the request header. ---- #### API令牌简介: ##### 方法一：在请求头中使用API令牌（推荐） - **请求头**: `Authorization` - **格式**: `Bearer {token}` - **示例**: `{"Authorization": "Bearer your_token"}` - **Swagger UI**: 点击页面右上角的`Authorize`按钮，直接输入API令牌，不需要`Bearer`关键字。 ##### 方法二：在Cookie中使用API令牌（不推荐，仅在无法使用方法一时使用） - **Cookie**: `Authorization` - **格式**: `Bearer {token}` - **示例**: `Authorization=Bearer your_token` #### 获取API令牌: 1. 在TikHub网站注册并登录账户。 2. 进入用户中心，点击API令牌菜单，创建API令牌。 3. 复制并在请求头中使用API令牌。 4. 保密您的API令牌，仅在请求头中使用。 scheme: bearer servers: - url: https://api.tikhub.io description: Production Environment security: [] ```