# 翻页

一次调用取一页，把 page.next_cursor 放进 cursor 就是下一页。每页算 1 次调用，单独计费，不会替你自动多翻。

## 游标

翻页只有游标一种方式。从这一页里拿 `page.next_cursor`，当作 `cursor` 发给**同一个接口，其余参数不变**。`page.has_more` 为 false 时没有下一页，`next_cursor` 是 `null`；`page.returned` 是这一页的条数。

cURL

```bash
curl -G "https://api.dataxapi.com/v1/tiktok/videos/search" \
  --data-urlencode "query=space station" \
  --data-urlencode "cursor=c1.bGY_kn5Dxsgl6MN3VXHyMcLAdlxPxQw-FwjswIlE" \
  -H "Authorization: Bearer $DATAXAPI_API_KEY"
```

CLI

```bash
dataxapi call tiktok.videos.search 'query=space station' cursor=c1.bGY_kn5Dxsgl6MN3VXHyMcLAdlxPxQw-FwjswIlE
```

## 每页条数和游标有效期

- 每页条数由平台决定。每个接口的页面写着通常几条、最多几条：`tiktok.videos.search` 每页大约 30 条，最多 30 条。
- 只有参数里列了 `limit` 的接口才能用它调每页条数，现在还没有这样的接口。
- 游标会过期。有效期写在每个接口的页面上（`tiktok.videos.search` 是 1 小时），每一页的 `page.cursor_expires_at` 是准确的到期时间。
- 一次给全的请求（例如某个榜）不返回游标。

## 报错

| 代码 | 状态码 | 意思 |
| --- | --- | --- |
| [`cursor_expired`](https://dataxapi.com/zh/docs/errors/#cursor_expired) | 410 | 游标已过期，请从第一页重新开始 |
| [`cursor_invalid`](https://dataxapi.com/zh/docs/errors/#cursor_invalid) | 400 | 游标不存在 |
| [`cursor_mismatch`](https://dataxapi.com/zh/docs/errors/#cursor_mismatch) | 400 | 游标不是用这个接口和这组参数取得的 |
| [`cursor_unavailable`](https://dataxapi.com/zh/docs/errors/#cursor_unavailable) | 502 | 这个游标所在的数据来源现在不可用，稍后重试或从第一页重新开始 |

这几种都不扣费。

## 用 SDK 和命令行连续翻页

服务不会替你多取一页。SDK 和命令行在你这边循环，一页一次调用，到你设的上限就停：条数、页数或金额。会让总额超过金额上限的那一页不会去取。

TypeScript

```ts
import { DataXAPI } from "@dataxapi/sdk";

const dx = new DataXAPI();
for await (const item of dx.items("tiktok.videos.search", { query: "space station" }, { maxItems: 100, maxSpend: "0.008" })) {
  console.log(item.id);
}
for await (const page of dx.pages("tiktok.videos.search", { query: "space station" }, { maxPages: 3 })) {
  console.log(page.page?.returned, page.meta.billing.amount);
}
```

Python

```python
from dataxapi import DataXAPI

dx = DataXAPI()
for item in dx.items("tiktok.videos.search", query="space station", max_items=100, max_spend="0.008"):
    print(item["id"])
for page in dx.pages("tiktok.videos.search", query="space station", max_pages=3):
    print(page["page"]["returned"], page["meta"]["billing"]["amount"])
```

CLI

```bash
dataxapi call tiktok.videos.search 'query=space station' --pages 3 --max-spend 0.006
```

## 翻页花多少钱

账单就是页数乘单价。`tiktok.videos.search` 每次 $0.0020，每页大约 30 条：

| 页数 | 大约几条 | 扣费 |
| --- | --- | --- |
| 1 | 30 | $0.0020 |
| 3 | 90 | $0.0060 |
| 10 | 300 | $0.0200 |

失败的那一页不扣费。哪些情况扣、哪些不扣，见[计费](https://dataxapi.com/zh/docs/billing/)。

---

目录修订号 c48ce454ae6c4c65。 [网页版](https://dataxapi.com/zh/docs/pagination/)