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

# Pagination

> Cursor-based pagination for discovery lists and historical time series.

Large result sets paginate with opaque cursors. Pass cursors verbatim — do not decode or construct them manually.

## Discovery lists

`GET /v1/series`, `/v1/events`, and `/v1/markets` return paginated catalogs:

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

**Rules**

* Pass `cursor=metadata.next_cursor` on the next request.
* Retain the same filters (`search`, `tags`, date bounds, `sort`, `order`).
* When `next_cursor` is `null`, you have reached the final page.

```bash theme={null}
curl -s -H "X-API-Key: $POLYORDERBOOKS_API_KEY" \
  "https://api.polyorderbooks.com/v1/markets" \
  --get \
  --data-urlencode "search=bitcoin" \
  --data-urlencode "limit=100" \
  --data-urlencode "cursor=MTAw"
```

## Historical time series

History endpoints paginate **time buckets** within `[start_ts, end_ts)`:

```json theme={null}
{
  "metadata": {
    "count": 100,
    "limit": 100,
    "next_cursor": "MjAyNi0wNy0yNlQwMTowMDowMFo="
  }
}
```

When following cursors on history endpoints, reuse the same `start_ts`, `end_ts`, and `resolution` from the initial request.

## Page size limits

| Endpoint type     | Default `limit` | Maximum `limit` |
| ----------------- | --------------- | --------------- |
| Discovery lists   | 100             | 1000            |
| Historical series | 100             | 200             |

<Warning>
  Do not construct or decode cursors manually. Treat them as opaque tokens returned by the API.
</Warning>