docs: document cursor-based pagination as recommended approach for /odds

Add ?cursor= param to odds.mdx and overview.mdx. Explain why offset-based
pagination drifts on live data, add a dedicated Pagination section with
full cURL/JS/Python examples using next_cursor, and update response JSON
samples to show next_cursor alongside next_offset.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Mlaz-code

content/en/api-reference/odds.mdx

@@ -37,7 +37,8 @@ The sportsbooks returned in your results depend on your subscription tier. Free
 | `group_by` | string | — | Group results by field (e.g., `event`) |
 | `state` | string | — | US state code for sportsbook deep links (e.g., `nj`, `ny`, `il`). When set, `deep_link` URLs include `?state=XX` so the redirect targets the correct state-specific sportsbook domain. Only affects books with state-dependent URLs (BetMGM, Caesars, BetRivers). |
 | `limit` | integer | 50 | Max results per page (max 200) |
-| `offset` | integer | 0 | Pagination offset (max 5000) |
+| `offset` | integer | 0 | Pagination offset. May produce duplicate rows when live data updates between requests — use `cursor` for multi-page scans. |
+| `cursor` | string | — | Opaque cursor from `next_cursor` in a previous response. **Recommended for multi-page scans** — stable against live data changes. Takes precedence over `offset` when both are provided. |
 
 <Callout type="info">
 Use comma-separated values to filter by multiple sportsbooks: `sportsbook=draftkings,fanduel,betmgm`
@@ -83,46 +84,83 @@ curl -X GET "https://api.sharpapi.io/api/v1/odds?league=nba&sportsbook=draftking
   </Tabs.Tab>
   <Tabs.Tab>
 ```javascript
-const response = await fetch(
-  'https://api.sharpapi.io/api/v1/odds?league=nba&sportsbook=draftkings&market=moneyline',
-  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
-);
-const { data, meta } = await response.json();
-console.log(`Received ${meta.count} of ${meta.total} odds`);
-
-// Paginate through results
-if (meta.pagination.has_more) {
-  const nextPage = await fetch(
-    `https://api.sharpapi.io/api/v1/odds?league=nba&sportsbook=draftkings&offset=${meta.pagination.next_offset}`,
-    { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
-  );
+// Fetch all NBA moneyline odds using cursor-based pagination (recommended)
+async function fetchAllOdds() {
+  const results = [];
+  let cursor = null;
+
+  do {
+    const url = new URL('https://api.sharpapi.io/api/v1/odds');
+    url.searchParams.set('league', 'nba');
+    url.searchParams.set('sportsbook', 'draftkings');
+    url.searchParams.set('market', 'moneyline');
+    url.searchParams.set('limit', '200');
+    if (cursor) url.searchParams.set('cursor', cursor);
+
+    const { data, pagination } = await fetch(url, {
+      headers: { 'X-API-Key': 'YOUR_API_KEY' }
+    }).then(r => r.json());
+
+    results.push(...data);
+    cursor = pagination.has_more ? pagination.next_cursor : null;
+  } while (cursor);
+
+  return results;
 }
 ```
   </Tabs.Tab>
   <Tabs.Tab>
 ```python
 import requests
 
-response = requests.get(
-    'https://api.sharpapi.io/api/v1/odds',
-    params={
-        'league': 'nba',
-        'sportsbook': 'draftkings',
-        'market': 'moneyline'
-    },
-    headers={'X-API-Key': 'YOUR_API_KEY'}
-)
-result = response.json()
-print(f"Found {result['meta']['count']} of {result['meta']['total']} odds")
-
-# Check for more pages
-if result['meta']['pagination']['has_more']:
-    next_offset = result['meta']['pagination']['next_offset']
-    print(f"Next page at offset {next_offset}")
+# Fetch all NBA moneyline odds using cursor-based pagination (recommended)
+def fetch_all_odds():
+    results = []
+    params = {'league': 'nba', 'sportsbook': 'draftkings', 'market': 'moneyline', 'limit': 200}
+    cursor = None
+
+    while True:
+        if cursor:
+            params['cursor'] = cursor
+        resp = requests.get(
+            'https://api.sharpapi.io/api/v1/odds',
+            params=params,
+            headers={'X-API-Key': 'YOUR_API_KEY'}
+        ).json()
+
+        results.extend(resp['data'])
+        pagination = resp['pagination']
+        if not pagination['has_more']:
+            break
+        cursor = pagination['next_cursor']
+
+    return results
 ```
   </Tabs.Tab>
 </Tabs>
 
+## Pagination
+
+<Callout type="warning">
+**Use cursor-based pagination for multi-page scans.** The `/odds` endpoint serves live data that refreshes every ~15 seconds. With offset-based pagination, rows can shift positions between requests, causing duplicates at page boundaries. Cursor-based pagination anchors each page to the last seen item — no drift.
+</Callout>
+
+Each response includes both `next_cursor` (stable) and `next_offset` (legacy) in the `pagination` object. For sequential full-dataset scans, always use `next_cursor`.
+
+```bash
+# First page — no cursor needed
+curl "https://api.sharpapi.io/api/v1/odds?league=nfl&limit=200" \
+  -H "X-API-Key: YOUR_API_KEY"
+
+# Subsequent pages — pass next_cursor from the previous response
+curl "https://api.sharpapi.io/api/v1/odds?league=nfl&limit=200&cursor=eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0" \
+  -H "X-API-Key: YOUR_API_KEY"
+```
+
+Cursors are opaque — do not parse or construct them. They encode the sort position of the last item on the current page and are only valid for the same filter parameters.
+
+`?offset=N` continues to work and is appropriate for single-page requests or direct position access. It is not recommended for iterating through live data.
+
 ## Response
 
 ### Success (200)
@@ -179,7 +217,8 @@ if result['meta']['pagination']['has_more']:
       "limit": 50,
       "offset": 0,
       "has_more": true,
-      "next_offset": 50
+      "next_offset": 50,
+      "next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
     },
     "updated_at": "2026-01-26T02:10:37.846Z",
     "filters": {
@@ -403,8 +442,8 @@ curl "https://api.sharpapi.io/api/v1/odds?league=nba&live=true" \
 curl "https://api.sharpapi.io/api/v1/odds?event=33483153&market=moneyline,spread" \
   -H "X-API-Key: YOUR_API_KEY"
 
-# Paginate through all NFL spread odds
-curl "https://api.sharpapi.io/api/v1/odds?league=nfl&market=spread&limit=100&offset=100" \
+# Paginate through all NFL spread odds (use next_cursor from each response)
+curl "https://api.sharpapi.io/api/v1/odds?league=nfl&market=spread&limit=200" \
   -H "X-API-Key: YOUR_API_KEY"
 ```
 

content/en/api-reference/overview.mdx

@@ -140,7 +140,8 @@ All successful responses wrap data in a consistent envelope:
     "limit": 50,
     "offset": 0,
     "has_more": true,
-    "next_offset": 50
+    "next_offset": 50,
+    "next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
   },
   "meta": {
     "count": 1,
@@ -149,7 +150,8 @@ All successful responses wrap data in a consistent envelope:
       "limit": 50,
       "offset": 0,
       "has_more": true,
-      "next_offset": 50
+      "next_offset": 50,
+      "next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
     },
     "updated_at": "2026-01-26T02:10:37.846Z",
     "filters": {
@@ -167,7 +169,8 @@ All successful responses wrap data in a consistent envelope:
 | `pagination.limit` | Maximum items per page (default: 50, max: 200) |
 | `pagination.offset` | Current offset into results |
 | `pagination.has_more` | Whether more results exist beyond this page |
-| `pagination.next_offset` | Offset value to use for the next page |
+| `pagination.next_offset` | Offset value to use for the next page (legacy — use `next_cursor` for live-data endpoints) |
+| `pagination.next_cursor` | Opaque cursor for the next page. Pass as `?cursor=` — stable against live data changes. Recommended for multi-page scans. |
 | `meta.count` | Number of items returned in this response |
 | `meta.total` | Total matching items across all pages |
 | `meta.pagination` | Same as top-level `pagination` (included for backward compatibility) |
@@ -265,7 +268,8 @@ All list endpoints support filtering via query parameters. Filters use **singula
 | `max_odds` | number | `200` | Maximum American odds filter |
 | `group_by` | string | `event` | Group results by field |
 | `limit` | number | `25` | Results per page (default: 50, max: 200) |
-| `offset` | number | `50` | Pagination offset |
+| `offset` | number | `50` | Pagination offset. May produce duplicate rows on live endpoints when data changes between requests. |
+| `cursor` | string | — | Opaque cursor from `next_cursor`. Recommended for multi-page scans over live data — eliminates offset drift. |
 
 ### Examples