next_cursor 是什么，为什么不能直接跳到第 5 页？

所有列表类接口都是一次返回一页，数据旁边带一个 page 对象：

"page": { "next_cursor": "c1.k3Vq9TzR0bYw2LmXe8NdPa", "has_more": true }

next_cursor 是个书签，记录这一页停在了哪里，内容只有服务端能读懂。要下一页，就把它作为 cursor 参数原样传回去。has_more 为 false 时，列表已经到底，也就没有游标了。

为什么没有“page=5”

按页码或偏移量翻页（page=5、offset=80），前提是服务端能数数、能跳过。各平台的信息流不是这么提供的。抖音每返回一批评论都附带一个位置指针，下一批就是这个位置之后的内容。小红书搜索倒是有页码，但每次请求还得带上前一页返回的会话参数，所以第一次请求不可能直接是第 5 页。Slack 工程团队在讲自家 API 时也说过同样的取舍：游标翻页在你翻页期间有新内容插进来也不会错乱，但没有总页数，客户端也没法跳到指定页。X 的 API 用 next_token，道理一样。

所以第 5 页只能从第 1 到第 4 页一路翻过去。游标也只属于生成它的那个请求：要发给同一个接口，query、id、sort 都保持不变；view 和 fields 可以在翻页时换。拿别的请求的游标来用，会在扣费之前就被拒绝，返回 cursor_mismatch；过了有效期的游标返回 cursor_expired，同样不扣费。

翻页怎么收费

一次调用返回一页，每一页都按一次调用计费。

要做的事	调用次数	费用
一个视频评论的第一页，约 20 条	1	$0.002
评论翻到第 5 页	5	$0.01
小红书搜 防晒霜，翻 5 页	5	$0.10
同样的搜索翻 20 页	20	$0.40

开始之前先想好要几页，够了就停。在代码里写死一个页数上限，比靠记性靠谱，也更省钱。

示例

import os, requests

URL = "https://api.okdata.online/v1/douyin/videos/comments/list"
KEY = os.environ["OKDATA_API_KEY"]

def comments(video_id: str, max_pages: int = 5):
    cursor, seen = None, set()
    for n in range(max_pages):
        params = {"id": video_id, "fields": "id,text,likes,published_at"}
        if cursor:
            params["cursor"] = cursor
        r = requests.get(URL, params=params, timeout=60, headers={
            "Authorization": f"Bearer {KEY}",
            "Idempotency-Key": f"dy-comments-{video_id}-{n}-{cursor or 'first'}",
        }).json()
        if r["code"] != "ok":
            raise RuntimeError(f'{r["code"]}: {r["message"]}')
        for c in r["data"]["items"]:
            if c["id"] not in seen:
                seen.add(c["id"])
                yield c
        if not r["page"]["has_more"]:
            return
        cursor = r["page"]["next_cursor"]

rows = list(comments("7412345678901234567", max_pages=5))
print(len(rows), "条评论")

幂等键里带着游标，超时之后重试这一页，拿到的是存好的结果，不会付两次钱。

限制

• 游标是用来“现在接着往下翻”的，不是留到下周再续的书签。游标因为 cursor_expired 被拒，就不带游标从头开始。
• 翻页期间列表在变：新评论进来、排序在动。所以要像上面的循环一样按 id 去重。
• 平台对列表能翻多深有上限，见小红书搜索为什么翻到两百来条就没了和抖音评论为什么比显示的评论数少。
• 完整的翻页约定见请求与响应；每个接口的页面，比如抖音视频评论和小红书笔记搜索，都写着每页条数。