# Pagination

One call returns one page; pass page.next_cursor back as cursor for the next. Each page is 1 call, charged on its own, and nothing is fetched behind your back.

## The cursor

The cursor is the only way to page. Take `page.next_cursor` from one page and send it as `cursor` to the **same endpoint with the same parameters**. When `page.has_more` is false there is no next page and `next_cursor` is `null`; `page.returned` says how many items the page holds.

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
```

## Page size and how long a cursor lasts

- The page size is the platform's. Each endpoint's page gives the usual size and the largest: `tiktok.videos.search` returns about 30 items a page, 30 at most.
- `limit` sets the size only on an endpoint that lists it among its parameters; none does today.
- A cursor expires. The lifetime is on each endpoint's page (1 hour for `tiktok.videos.search`), and every page carries the exact time in `page.cursor_expires_at`.
- A request that is answered whole (a board, for example) returns no cursor.

## Errors

| Code | Status | What it means |
| --- | --- | --- |
| [`cursor_expired`](https://dataxapi.com/docs/errors/#cursor_expired) | 410 | The cursor expired; start again from the first page |
| [`cursor_invalid`](https://dataxapi.com/docs/errors/#cursor_invalid) | 400 | The cursor does not exist |
| [`cursor_mismatch`](https://dataxapi.com/docs/errors/#cursor_mismatch) | 400 | The cursor was issued for another endpoint or other parameters |
| [`cursor_unavailable`](https://dataxapi.com/docs/errors/#cursor_unavailable) | 502 | The data source this cursor belongs to is unavailable; retry later or start again from the first page |

None of these is charged.

## Walk pages with the SDKs and the command line

The service never fetches a page you did not ask for. The SDKs and the command line loop on your side, one call a page, and stop at the limits you set: items, pages, or money. A page that could take the total past the money limit is not fetched.

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
```

## What paging costs

The bill is the number of pages times the price. For `tiktok.videos.search` at $0.0020 a call and about 30 items a page:

| Pages | Items, about | Charged |
| --- | --- | --- |
| 1 | 30 | $0.0020 |
| 3 | 90 | $0.0060 |
| 10 | 300 | $0.0200 |

A page that fails is not charged. More on what is and is not charged: [Billing](https://dataxapi.com/docs/billing/).

---

Catalog revision c48ce454ae6c4c65. [HTML version](https://dataxapi.com/docs/pagination/)