douyin/creator-v2/item-list

Fetch item list

Purpose:

• Get all published items within the specified time range
• Support pagination query, maximum 100 items per request
• Data update description:
  • Views, likes, comments, shares, favorites update in real-time
  • Other metrics update hourly
• 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_time: Start timestamp in milliseconds (required)
• end_time: End timestamp in milliseconds (required)
• count: Number of items per page, default 10, max 100 (optional)
• order_by: Sort method, supports 26 types (optional, default 1)
• fields: Fields to return, default "metrics,review,visibility" (optional)
  • metrics: Traffic metrics (views, likes, comments, shares, favorites, etc.)
  • review: Review status
  • visibility: Visibility status
• need_cooperation: Need cooperation info, default true (optional)
• need_long_article: Include long articles, default true (optional)
• cursor: Pagination cursor, don't pass for first request, use returned cursor for pagination (optional)

Sort Options (order_by):

Value	Sort Field	Direction	Update Freq	Description
1	Publish Time	Desc ↓	-	Default, newest first
2	Publish Time	Asc ↑	-	Oldest first
3	Views	Desc ↓	Real-time	Video views count
4	Views	Asc ↑	Real-time	Least views first
5	Likes	Desc ↓	Real-time	Likes count
6	Likes	Asc ↑	Real-time	Least likes first
7	Comments	Desc ↓	Real-time	Comments count
8	Comments	Asc ↑	Real-time	Least comments first
9	Shares	Desc ↓	Real-time	Shares count
10	Shares	Asc ↑	Real-time	Least shares first
11	Favorites	Desc ↓	Real-time	Favorites count
12	Favorites	Asc ↑	Real-time	Least favorites first
13	2s Bounce Rate	Desc ↓	Hourly	Views bounced within 2s / total views
14	2s Bounce Rate	Asc ↑	Hourly	Lowest bounce rate first
15	5s Completion	Desc ↓	Hourly	Views over 5s / total views
16	5s Completion	Asc ↑	Hourly	Lowest 5s completion first
17	Completion Rate	Desc ↓	Hourly	Full plays / total views
18	Completion Rate	Asc ↑	Hourly	Lowest completion rate first
19	Cover CTR	Desc ↓	Hourly	Cover clicks / cover impressions
20	Cover CTR	Asc ↑	Hourly	Lowest CTR first
21	Avg Play Duration	Desc ↓	Hourly	Average video play duration
22	Avg Play Duration	Asc ↑	Hourly	Shortest duration first
23	Profile Visits	Desc ↓	Daily	Profile visits after watching
24	Profile Visits	Asc ↑	Daily	Least profile visits first
25	Follower Growth	Desc ↓	Hourly	New followers from this video
26	Follower Growth	Asc ↑	Hourly	Least follower growth first

Sort Usage Tips:

• Find Hits: Use order_by=3 (Views↓) or order_by=5 (Likes↓)
• Content Optimization: Use order_by=13 (Bounce Rate↓) to find videos to improve
• Improve Completion: Use order_by=17 (Completion↓) to analyze high-completion videos
• Follower Analysis: Use order_by=25 (Follower Growth↓) to find best performing videos
• Cover Optimization: Use order_by=19 (Cover CTR↓) to analyze cover attractiveness

Return:

• Item list data with detailed metric information
• has_more: Whether there are more items
• cursor: Cursor for next page, used for pagination
• items: Array of items

Usage Flow:

1. First request: Don't pass cursor parameter, get first page
2. Check has_more: If true, there are more items
3. Paginate: Use returned cursor value as cursor parameter for next request
4. Repeat steps 2-3: Until has_more is false

Limitations:

• Only supports filtering: Top 100 items by genre in selected period
• For exporting more data, use /fetch_item_list_download API (supports top 1000 items)

Timestamp Conversion:

• JavaScript: new Date('2025-07-01').getTime() -> 1719763200000
• Python: int(datetime(2025, 7, 1).timestamp() * 1000) -> 1719763200000

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_time": 1758988800000,
    "end_time": 1760198399000,
    "count": 10
}

{
    "cookie": "Your_Cookie_Here",
    "start_time": 1758988800000,
    "end_time": 1760198399000,
    "count": 20,
    "order_by": 3
}

{
    "cookie": "Your_Cookie_Here",
    "start_time": 1758988800000,
    "end_time": 1760198399000,
    "count": 20,
    "order_by": 17
}

{
    "cookie": "Your_Cookie_Here",
    "start_time": 1758988800000,
    "end_time": 1760198399000,
    "count": 20,
    "order_by": 25
}

{
    "cookie": "Your_Cookie_Here",
    "start_time": 1758988800000,
    "end_time": 1760198399000,
    "count": 10,
    "cursor": 1234567890
}

{
    "has_more": true,
    "cursor": 1234567890,
    "items": [
        {
            "item_id": "7559536212910853422",
            "metrics": {
                "play_count": 12345,
                "digg_count": 678,
                "comment_count": 90,
                "share_count": 45,
                "collect_count": 123
            },
            "review": {
                "status": 2
            },
            "visibility": {
                "is_public": true
            }
        }
    ]
}

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