douyin/creator-v2/live-room-history-list

Fetch live room history list

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]

{
    "cookie": "Your_Cookie_Here",
    "start_date": "2025-09-11",
    "end_date": "2025-10-11",
    "limit": 400,
    "need_living": 1,
    "download": 0
}

{
    "data": {
        "code": 0,
        "componentID": "",
        "data": {
            "series": [
                {
                    "clientCommentUcntTd": "0",
                    "coverUri": "https://p3-webcast-sign.douyinpic.com/...",
                    "endTime": "2025-11-20 13:52:20",
                    "liveConsumeUcnt": "1",
                    "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": ""
    }
}

Imported from a validated TikHub OpenAPI document. Pricing must be reviewed before enabling.