# What is next_cursor, and why can't I jump straight to page 5?

> How cursor paging works on a social data API: what next_cursor and has_more mean, why there is no page number to jump to, what each page costs, and a safe loop with a page cap.

Canonical page: https://okdata.online/answers/api-cursor-next-page/

**Short answer: **next_cursor is an opaque bookmark for where the last page stopped; you send it back unchanged as cursor to get the next page. The platforms' own feeds only know what comes after a point, so page 5 means fetching pages 1 to 4 first. Each page is one call and one charge: five pages of Douyin comments cost $0.01 on okdata.

Every list endpoint returns one page at a time, with a `page` object next to the items:

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

`next_cursor` is a bookmark. It records where this page stopped, in a form only the server can read. To get the next page, send it back as the `cursor` parameter, exactly as you received it. When `has_more` is false, the list is finished and there is no cursor.

## Why there is no "page=5"

Offset paging (`page=5`, `offset=80`) needs a server that can count and skip. The platforms do not serve their feeds that way. Douyin returns a pointer with each batch of comments, and the next batch is whatever follows it. Xiaohongshu search does number its pages, but each request must also carry session values that the previous page returned, so page 5 cannot be the first request. Slack's engineering team describes the same trade-off for its own API: cursors stay correct when items are added while you page, but there is no total page count and the client cannot jump to a specific page. X's API works the same way with its `next_token`.

So page 5 is reachable only through pages 1 to 4. A cursor also belongs to the request it came from: send it to the same endpoint with the same query, id and sort. `view` and `fields` may change between pages. A cursor that belongs to another request is refused as `cursor_mismatch`, and one past its lifetime as `cursor_expired`, before anything is charged.

## What paging costs

One call returns one page, and each page is billed as its own call.

| Job | Calls | Cost |
|---|---|---|
| First page of a video's comments, about 20 | 1 | $0.002 |
| Comments up to page 5 | 5 | $0.01 |
| Xiaohongshu search for `防晒霜`, 5 pages | 5 | $0.10 |
| The same search, 20 pages | 20 | $0.40 |

Decide how many pages you need before you start, and stop as soon as you have them. A fixed page cap in code is cheaper than a promise to remember.

## Example

```python
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), "comments")
```

The idempotency key includes the cursor, so a retry after a timeout replays that page instead of paying for it twice.

## Limits

- Use a cursor to continue a listing now, not as a bookmark to resume next week. If one is refused as `cursor_expired`, start again without a cursor.
- Lists move while you page. New comments arrive and rankings shift, so deduplicate by `id` as the loop above does.
- Platforms cap how deep a list goes; see [why Xiaohongshu search stops after a couple of hundred notes](/answers/xiaohongshu-search-result-limit/) and [why you get fewer Douyin comments than the counter shows](/answers/douyin-comments-incomplete/).
- The [requests page](/docs/requests/) has the full paging contract; the endpoint pages, such as [Douyin video comments](/apis/douyin/videos/comments/list/) and [Xiaohongshu note search](/apis/xiaohongshu/notes/search/), list each endpoint's page size.

## Endpoints used

- [Douyin video comments](https://okdata.online/apis/douyin/videos/comments/list/) `douyin.videos.comments.list`: $0.002 per call · about 20 comments per page
- [Xiaohongshu note search](https://okdata.online/apis/xiaohongshu/notes/search/) `xiaohongshu.notes.search`: $0.02 per call · about 20 notes per page

## More about Douyin

- [Douyin API](https://okdata.online/apis/douyin/)
- [Douyin API in Python: videos, profiles and comments (2026)](https://okdata.online/guides/douyin-api-python/)
- [How to export Douyin video comments in bulk](https://okdata.online/guides/douyin-video-comments/)
- [How to find Douyin Xingtu creators and get their rate cards](https://okdata.online/guides/douyin-xingtu-creator-rates/)
- [Xiaohongshu API in Python: notes, profiles and comments (2026)](https://okdata.online/guides/xiaohongshu-api-python/)
- [How to export Xiaohongshu comments for a keyword](https://okdata.online/guides/xiaohongshu-note-comments/)
- [How to search Xiaohongshu notes and export them to CSV](https://okdata.online/guides/xiaohongshu-search-export-notes/)
- [How do I write a Claude Code skill that pulls Douyin comments or Xiaohongshu notes?](https://okdata.online/answers/agent-skill-social-media-data/)
- [How do I use an LLM to find customer pain points in Douyin and Xiaohongshu comments?](https://okdata.online/answers/llm-comment-pain-points-douyin-xiaohongshu/)
- [MediaCrawler keeps breaking for me. Is a paid API worth it instead?](https://okdata.online/answers/mediacrawler-alternative-paid-api/)
- [Is there an MCP or API version of MediaCrawler for AI agents?](https://okdata.online/answers/mediacrawler-mcp-for-ai-agents/)
- [Where does an n8n workflow get Xiaohongshu or Douyin data from?](https://okdata.online/answers/n8n-xiaohongshu-douyin-data/)
- [How to collect Douyin comments: API, crawler or no-code (2026)](https://okdata.online/compare/douyin-comment-scraping/)
- [Douyin data APIs: official vs third-party vs open-source (2026)](https://okdata.online/compare/douyin-data-apis/)

## Sources

- [Evolving API Pagination at Slack (offset vs cursor paging)](https://slack.engineering/evolving-api-pagination-at-slack/) (read 2026-11-12)
- [X API docs: Pagination with next_token](https://docs.x.com/x-api/fundamentals/pagination) (read 2026-11-12)

Where people asked this (read 2026-11-12): 

- https://stackoverflow.com/questions/60622392
- https://stackoverflow.com/questions/27868922
- https://github.com/davidteather/TikTok-Api/issues/1183

Updated 2026-11-12