> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarketdata.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Walk discovery and history pages with metadata.next_cursor.

List and history endpoints return a page plus opaque cursor metadata. Do not invent offsets.

## Response metadata

Discovery list endpoints (`/v1/series`, `/v1/events`, `/v1/markets`):

```json theme={null}
{
  "metadata": {
    "count": 100,
    "limit": 100,
    "next_cursor": "eyJ2IjoiMjAyNS0wNi0wNVQxMjozNDo1NiswMDowMCIsImlkIjoiMTAxIn0="
  },
  "data": []
}
```

History endpoints use the same cursor fields on `metadata`. `next_cursor` is `null` (or omitted) when the page is complete.

## Limits

| Family    | Default `limit` | Maximum `limit` |
| --------- | --------------- | --------------- |
| Discovery | 100             | 1000            |
| History   | 100             | 200             |

<Warning>
  Market-level price and book responses include one series per token. `limit` is a point budget for the page. If the market has several tokens, you may need a higher `limit`, or you will get `limit too small for this market`.
</Warning>

## Walk every page

```python theme={null}
import os
import requests

headers = {"X-API-Key": os.environ["POLYMARKETDATA_API_KEY"]}
url = "https://api.polymarketdata.co/v1/markets"
params = {"search": "election", "limit": 100}
cursor = None
markets = []

while True:
    if cursor:
        params["cursor"] = cursor
    response = requests.get(url, headers=headers, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()
    markets.extend(payload["data"])
    cursor = payload.get("metadata", {}).get("next_cursor")
    if not cursor:
        break

print(len(markets))
```

The Python SDK exposes the same loop as iterators: `iter_markets()`, `iter_series()`, `iter_events()`, plus history iterators such as `iter_market_metrics()`.

## Invalid cursors

A malformed or expired cursor returns `400`:

```json theme={null}
{ "detail": "Invalid pagination cursor" }
```

Start the listing again from the first page. Do not retry the same cursor.