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

# Pagination Guide

> Learn how to paginate through API results efficiently

# Pagination Guide

Many endpoints support cursor-based pagination to efficiently navigate through large result sets. Here's how to use it:

## Basic Usage

Most list endpoints support two query parameters:

* **`limit`** - Number of results per page (1-25, default varies by endpoint)
* **`cursor`** - Opaque token for fetching the next page

## Making Your First Request

```bash theme={null}
curl "https://api-v2.polyrouter.io/markets?limit=10" \
  -H "X-API-Key: 5fa709a5-0634-44c3-a991-57166d3c376d"
```

The response includes a `pagination` object:

```json theme={null}
{
  "markets": [...],
  "pagination": {
    "total": 150,
    "limit": 10,
    "has_more": true,
    "next_cursor": "eyJwbGF0Zm9ybXMiOnsia2Fsc2hpIjp7..."
  }
}
```

## Getting the Next Page

Use the `next_cursor` from the previous response:

```bash theme={null}
curl "https://api-v2.polyrouter.io/markets?limit=10&cursor=eyJwbGF0Zm9ybXMiOnsia2Fsc2hpIjp7..." \
  -H "X-API-Key: 5fa709a5-0634-44c3-a991-57166d3c376d"
```

## Complete Example

> [tab] JavaScript
>
> ```javascript theme={null}
> async function fetchAllMarkets() {
>   const allMarkets = [];
>   let cursor = null;
>   let hasMore = true;
>
>   while (hasMore) {
>     const url = cursor 
>       ? `https://api-v2.polyrouter.io/markets?cursor=${cursor}&limit=25`
>       : `https://api-v2.polyrouter.io/markets?limit=25`;
>
>     const response = await fetch(url, {
>       headers: {
>         'X-API-Key': '5fa709a5-0634-44c3-a991-57166d3c376d'
>       }
>     });
>
>     const data = await response.json();
>     allMarkets.push(...data.markets);
>
>     hasMore = data.pagination.has_more;
>     cursor = data.pagination.next_cursor;
>   }
>
>   return allMarkets;
> }
> ```

> [tab] Python
>
> ```python theme={null}
> import requests
>
> def fetch_all_markets():
>     all_markets = []
>     cursor = None
>     has_more = True
>
>     headers = {'X-API-Key': '5fa709a5-0634-44c3-a991-57166d3c376d'}
>
>     while has_more:
>         url = 'https://api-v2.polyrouter.io/markets'
>         params = {'limit': 25}
>         if cursor:
>             params['cursor'] = cursor
>
>         response = requests.get(url, headers=headers, params=params)
>         data = response.json()
>
>         all_markets.extend(data['markets'])
>         has_more = data['pagination']['has_more']
>         cursor = data['pagination'].get('next_cursor')
>
>     return all_markets
> ```

> [tab] cURL
>
> ```bash theme={null}
> # First page
> curl "https://api-v2.polyrouter.io/markets?limit=25" \
>   -H "X-API-Key: 5fa709a5-0634-44c3-a991-57166d3c376d"
>
> # Next page (use next_cursor from response)
> curl "https://api-v2.polyrouter.io/markets?limit=25&cursor=eyJ..." \
>   -H "X-API-Key: 5fa709a5-0634-44c3-a991-57166d3c376d"
> ```

## Important Notes

> [!WARNING]
>
> **Changing filters mid-pagination:** If you change query parameters (like `platform`, `status`, or `query`) between requests, the cursor will be invalidated. Start pagination from the first page when changing filters.

> [!NOTE]
>
> **Cursor lifespan:** Cursors are designed for immediate use within a pagination session. Don't store them long-term as they may become invalid.

## Pagination Tips

1. **Choose appropriate limits:**
   * Use `limit=25` (maximum) for bulk operations
   * Use smaller limits (5-10) for real-time updates
   * Default limits vary by endpoint

2. **Check for more pages:** Always check `has_more` or whether `next_cursor` is `null` before making another request

3. **Rate limits:** Even with cursors, you're still subject to rate limits (100 req per minute)

4. **Platform filtering:** When using `platform` parameter, only one platform value is supported per query (not comma-separated)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.