获取投稿作品列表/Fetch item list

[中文]

用途:

• 获取指定时间范围内发布的所有投稿作品列表
• 支持分页查询，每次最多返回100条数据
• 数据更新说明：
  • 播放量、点赞量、评论量、分享量、收藏量实时更新
  • 其他指标每小时更新一次
• 此接口需要用户提供有效的抖音创作者平台Cookie
• 使用 POST 方法，Cookie 在请求体中传输，更安全

请求体参数:

• cookie: 用户的抖音创作者平台Cookie（必填，在请求体中传输）
• start_time: 开始时间戳，单位毫秒（必填）
• end_time: 结束时间戳，单位毫秒（必填）
• count: 每页返回的数量，默认10，最多100（可选）
• order_by: 排序方式，支持26种排序（可选，默认1）
• fields: 需要返回的字段，默认 "metrics,review,visibility"（可选）
  • metrics: 流量指标（播放量、点赞量、评论量、分享量、收藏量等）
  • review: 审核状态
  • visibility: 可见性状态
• need_cooperation: 是否需要合作信息，默认true（可选）
• need_long_article: 是否包含长图文，默认true（可选）
• cursor: 分页游标，首次请求不传，后续分页使用返回的cursor（可选）

排序方式详解 (order_by):

值	排序字段	排序方向	更新频率	说明
1	发布时间	从新到旧 ↓	-	默认排序，最新发布的在前
2	发布时间	从旧到新 ↑	-	最早发布的在前
3	播放量	从高到低 ↓	实时	作品被观看的次数
4	播放量	从低到高 ↑	实时	播放量最少的在前
5	点赞量	从高到低 ↓	实时	作品获得点赞的次数
6	点赞量	从低到高 ↑	实时	点赞量最少的在前
7	评论量	从高到低 ↓	实时	作品获得评论的次数
8	评论量	从低到高 ↑	实时	评论量最少的在前
9	分享量	从高到低 ↓	实时	作品获得分享的次数
10	分享量	从低到高 ↑	实时	分享量最少的在前
11	收藏量	从高到低 ↓	实时	作品获得收藏的次数
12	收藏量	从低到高 ↑	实时	收藏量最少的在前
13	2s跳出率	从高到低 ↓	每小时	播放后2s内跳出的播放量/总播放量
14	2s跳出率	从低到高 ↑	每小时	2s跳出率最低的在前
15	5s完播率	从高到低 ↓	每小时	播放后超过5s的播放量/总播放量
16	5s完播率	从低到高 ↑	每小时	5s完播率最低的在前
17	完播率	从高到低 ↓	每小时	完整播完的播放量/总播放量
18	完播率	从低到高 ↑	每小时	完播率最低的在前
19	封面点击率	从高到低 ↓	每小时	作品封面的点击量/曝光量
20	封面点击率	从低到高 ↑	每小时	封面点击率最低的在前
21	平均播放时长	从高到低 ↓	每小时	视频被播放的平均时长
22	平均播放时长	从低到高 ↑	每小时	平均播放时长最短的在前
23	主页访问量	从高到低 ↓	每天	用户观看作品后访问主页的次数
24	主页访问量	从低到高 ↑	每天	主页访问量最少的在前
25	粉丝增量	从高到低 ↓	每小时	观众观看作品后关注作者的数量
26	粉丝增量	从低到高 ↑	每小时	粉丝增量最少的在前

排序使用建议:

• 寻找爆款: 使用 order_by=3 (播放量↓) 或 order_by=5 (点赞量↓)
• 优化内容: 使用 order_by=13 (2s跳出率↓) 找出需要优化的作品
• 提升完播: 使用 order_by=17 (完播率↓) 分析高完播率作品
• 涨粉分析: 使用 order_by=25 (粉丝增量↓) 找出涨粉效果好的作品
• 封面优化: 使用 order_by=19 (封面点击率↓) 分析封面吸引力

返回:

• 投稿作品列表数据，包含作品的详细指标信息
• has_more: 是否还有更多数据
• cursor: 下一页的游标，用于分页查询
• items: 作品列表数组

使用流程:

1. 第一次请求：不传cursor参数，获取第一页数据
2. 检查has_more：如果为true，说明还有更多数据
3. 分页请求：使用返回的cursor值作为下次请求的cursor参数
4. 重复步骤2-3：直到has_more为false

功能限制:

• 仅支持筛选：所选周期内，前100条作品的体裁
• 如需导出更多数据，请使用 /fetch_item_list_download 接口（支持导出前1000条）

时间戳转换:

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

Cookie 获取方式:

1. 登录抖音创作者平台 (https://creator.douyin.com)
2. 打开浏览器开发者工具（F12）
3. 切换到 Network 标签
4. 刷新页面或进行操作
5. 找到任意请求，复制 Cookie 请求头的值

[English]

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]

基础请求/Basic Request (默认按发布时间排序):

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

按播放量排序/Sort by Views (找爆款视频):

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

按完播率排序/Sort by Completion Rate (优质内容分析):

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

按粉丝增量排序/Sort by Follower Growth (涨粉效果分析):

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

分页请求/Pagination Request:

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

返回数据示例/Response Example:

{
    "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
            }
        }
    ]
}

注意事项/Notes:

1. 时间范围: 建议不要设置过长的时间范围，可能导致请求超时
2. 分页查询: 如果has_more=true，务必使用返回的cursor继续请求
3. 数据更新频率:
   • 实时更新：播放量、点赞量、评论量、分享量、收藏量
   • 每小时更新：跳出率、完播率、封面点击率、平均播放时长、粉丝增量
   • 每天更新：主页访问量
4. 数据量限制: 单次请求最多返回100条，如需更多请使用分页或导出接口
5. 体裁筛选: 仅支持前100条作品的体裁筛选
6. 排序选择: 根据分析目标选择合适的排序方式（共26种）
7. Cookie有效性: 如果返回错误，请检查Cookie是否过期
8. 排序说明: ↓表示从高到低，↑表示从低到高

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