Odds Snapshot

Get a snapshot of current odds from sportsbooks.


GET /api/v1/odds

Authentication

Requires API key. Available to all tiers.

The sportsbooks returned in your results depend on your subscription tier. Free tier users receive odds from DraftKings and FanDuel only. See Book Access by Tier below.

Query Parameters

Parameter	Type	Default	Description
`sportsbook`	string	tier-allowed	Comma-separated sportsbook IDs (e.g., `draftkings,fanduel`). Tier limits enforced.
`sport`	string	all	Filter by sport(s), comma-separated (e.g., `basketball`, `football`). Supports category aliases.
`league`	string	all	Filter by league(s), comma-separated (e.g., `nba`, `nfl`, `nhl`)
`market`	string	all	Filter by market type(s), comma-separated. Supports category aliases (`main`, `spread`, `total`, `props`) or exact types (`point_spread`, `player_points`).
`event`	string	—	Filter by event ID(s), comma-separated
`live`	boolean	—	`true` = live only, `false` = prematch only, omit = both
`sort`	string	—	Sort field with optional `-` prefix for descending (e.g., `-odds_american`, `odds_probability`)
`fields`	string	all	Comma-separated field names to include in response (e.g., `id,sportsbook,odds_american`)
`min_odds`	number	—	Minimum American odds filter (e.g., `-110`)
`max_odds`	number	—	Maximum American odds filter (e.g., `+200`)
`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. Must be ≤ 500. Values above 500 return `400 offset_too_large` — use `cursor` for deeper pagination. May produce duplicate rows when live data updates between requests.
`cursor`	string	—	Opaque cursor from `next_cursor` in a previous response. Required for deep pagination (past offset 500) and recommended for any multi-page scan — stable against live data changes. Takes precedence over `offset` when both are provided.

Use comma-separated values to filter by multiple sportsbooks: sportsbook=draftkings,fanduel,betmgm

Market Category Aliases

Instead of listing individual market types, you can use a category alias to match a group of related markets. Aliases and exact types can be mixed freely in a comma-separated list.

Alias	Expands to
`main`	`moneyline`, `point_spread`, `total_points`
`spread`	`point_spread`, `puck_line`, `run_line`, `set_handicap`
`total`	`total_points`, `total_goals`, `total_runs`, `total_games`, `total_rounds`, `team_total`
`props`	All `player_*` market types (prefix match)


# Fetch all "main" markets (moneyline + spreads + totals)
curl "https://api.sharpapi.io/api/v1/odds?league=nba&market=main" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Mix an alias with an exact type
curl "https://api.sharpapi.io/api/v1/odds?league=nfl&market=spread,moneyline" \
  -H "X-API-Key: YOUR_API_KEY"
 
# All player prop markets
curl "https://api.sharpapi.io/api/v1/odds?league=nba&market=props" \
  -H "X-API-Key: YOUR_API_KEY"

The props alias uses a prefix match, so it automatically includes any market type starting with player_ (e.g., player_points, player_rebounds, player_assists, player_strikeouts, etc.).

Example Requests

cURL


curl -X GET "https://api.sharpapi.io/api/v1/odds?league=nba&sportsbook=draftkings&market=moneyline" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript


// 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;
}

Python


import requests
 
# 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

Pagination

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.

Each response includes both next_cursor (stable) and next_offset (legacy) in the pagination object. For sequential full-dataset scans, always use next_cursor.


# 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 for shallow pagination (up to offset 500) and is appropriate for single-page requests or direct position access. Beyond 500, the API returns 400 offset_too_large — the server would otherwise have to sort the full filtered result set on every page, which is much cheaper to avoid than to optimize per-request. Use cursor for anything deeper.


{
  "error": {
    "code": "offset_too_large",
    "message": "offset must be <= 500; use `cursor=` from the previous response for deeper pagination",
    "max_offset": 500
  }
}

Response

Success (200)


{
  "success": true,
  "data": [
    {
      "id": "draftkings_33483153_moneyline_PHO",
      "sportsbook": "draftkings",
      "event_id": "33483153",
      "sport": "basketball",
      "league": "nba",
      "home_team": "PHI 76ers",
      "away_team": "PHO Suns",
      "market_type": "moneyline",
      "selection": "PHO Suns",
      "selection_type": "away",
      "odds_american": -150,
      "odds_decimal": 1.667,
      "odds_probability": 0.60,
      "line": null,
      "event_start_time": "2026-01-26T19:00:00Z",
      "last_seen_at": "2026-01-26T02:10:24.125Z",
      "is_live": false
    },
    {
      "id": "draftkings_33483153_moneyline_PHI",
      "sportsbook": "draftkings",
      "event_id": "33483153",
      "sport": "basketball",
      "league": "nba",
      "home_team": "PHI 76ers",
      "away_team": "PHO Suns",
      "market_type": "moneyline",
      "selection": "PHI 76ers",
      "selection_type": "home",
      "odds_american": 130,
      "odds_decimal": 2.30,
      "odds_probability": 0.4348,
      "line": null,
      "event_start_time": "2026-01-26T19:00:00Z",
      "last_seen_at": "2026-01-26T02:10:24.125Z",
      "is_live": false
    }
  ],
  "meta": {
    "count": 2,
    "total": 3095,
    "books_available": ["draftkings", "fanduel", "betmgm", "caesars", "pinnacle"],
    "books_returned": ["draftkings"],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "has_more": true,
      "next_offset": 50,
      "next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
    },
    "updated_at": "2026-01-26T02:10:37.846Z",
    "filters": {
      "league": "nba",
      "sportsbook": "draftkings",
      "market": "moneyline"
    }
  }
}

Response Headers


X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1737853200
X-Data-Delay: 0
X-Request-Id: req_abc123def456

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute for your tier
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets
`X-Data-Delay`	Data delay in seconds (0 for real-time, 60 for free tier)
`X-Request-Id`	Unique request identifier for debugging

Error Responses

401 Unauthorized


{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "docs": "https://docs.sharpapi.io/en/authentication"
  }
}

403 Tier Restricted


{
  "error": {
    "code": "tier_restricted",
    "message": "Sportsbook 'pinnacle' requires Sharp tier or higher",
    "docs": "https://docs.sharpapi.io/en/pricing"
  }
}

429 Rate Limited


{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "docs": "https://docs.sharpapi.io/en/authentication#rate-limits"
  }
}

Odds Object Schema

Field	Type	Description
`id`	string	Unique odds identifier
`sportsbook`	string	Sportsbook ID (e.g., `draftkings`)
`event_id`	string	Event identifier
`sport`	string	Sport slug (e.g., `basketball`, `football`)
`league`	string	League slug (e.g., `nba`, `nfl`)
`home_team`	string	Home team name
`away_team`	string	Away team name
`market_type`	string	`moneyline`, `spread`, `total`, `player_prop`, etc.
`selection`	string	The selection (team name, Over/Under, player name)
`selection_type`	string	`home`, `away`, `over`, `under`
`odds_american`	number	American odds (e.g., -110, +150)
`odds_decimal`	number	Decimal odds (e.g., 1.909)
`odds_probability`	number	Implied probability (e.g., 0.5238)
`line`	number \| null	Spread or total line value (`null` for moneyline)
`event_start_time`	string	ISO 8601 event start time
`last_seen_at`	string	ISO 8601 timestamp of our adapter’s last observation of this row. Updates every ingest cycle — this is the pipeline freshness signal.
`odds_changed_at`	string	ISO 8601 timestamp of the sportsbook’s own source update for this line, when available. On Pinnacle, carries forward while the price/line/`is_live` flag are unchanged (see Understanding Pinnacle’s `odds_changed_at`). Use `last_seen_at` for pipeline freshness.
`is_live`	boolean	Whether the event is currently live
`player_name`	string\|undefined	Player name (player prop markets only)
`stat_category`	string\|undefined	Stat category, e.g. `points`, `rebounds` (player prop markets only)
`public_bet_pct`	number\|undefined	Public betting ticket percentage (0.0-1.0). Currently BetMGM only.
`max_bet`	number\|undefined	Maximum wager amount (USD) for this market type. Currently Pinnacle only.

Sorting

Use the sort parameter to order results by any field. Prefix with - for descending order.


# Sort by best American odds (descending)
curl "https://api.sharpapi.io/api/v1/odds?league=nba&sort=-odds_american" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Sort by odds_probability (ascending)
curl "https://api.sharpapi.io/api/v1/odds?league=nba&sort=odds_probability" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Sort by event start time
curl "https://api.sharpapi.io/api/v1/odds?sort=event_start_time" \
  -H "X-API-Key: YOUR_API_KEY"

Valid sort fields: odds_american, odds_decimal, odds_probability, event_start_time, last_seen_at, sportsbook, league, sport.

Field Selection

Use the fields parameter to return only specific fields, reducing payload size.


# Only return id, sportsbook, and American odds
curl "https://api.sharpapi.io/api/v1/odds?league=nba&fields=id,sportsbook,odds_american" \
  -H "X-API-Key: YOUR_API_KEY"

The response will only include the requested fields for each odds object:


{
  "data": [
    {
      "id": "draftkings_33483153_moneyline_PHO",
      "sportsbook": "draftkings",
      "odds_american": -150
    }
  ]
}

Odds Range Filtering

Use min_odds and max_odds to filter by American odds value.


# Only return plus-money odds (+100 and above)
curl "https://api.sharpapi.io/api/v1/odds?league=nba&min_odds=100" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Only return odds between -200 and +200
curl "https://api.sharpapi.io/api/v1/odds?league=nba&min_odds=-200&max_odds=200" \
  -H "X-API-Key: YOUR_API_KEY"

Event-Grouped Response

Use group_by=event to group odds by event instead of a flat list. This is useful for building event-centric UIs.


curl "https://api.sharpapi.io/api/v1/odds?league=nba&group_by=event" \
  -H "X-API-Key: YOUR_API_KEY"


{
  "data": [
    {
      "event_id": "33483153",
      "event_name": "PHI 76ers vs PHO Suns",
      "sport": "basketball",
      "league": "nba",
      "start_time": "2026-01-26T19:00:00Z",
      "is_live": false,
      "odds": [
        {
          "id": "draftkings_33483153_moneyline_PHO",
          "sportsbook": "draftkings",
          "market_type": "moneyline",
          "selection": "PHO Suns",
          "selection_type": "away",
          "odds_american": -150,
          "odds_decimal": 1.667,
          "odds_probability": 0.60,
          "line": null,
          "last_seen_at": "2026-01-26T02:10:24.125Z"
        }
      ]
    }
  ],
  "meta": {
    "group_by": "event",
    "books_available": 5,
    "filters": { "league": "nba" },
    "updated_at": "2026-01-26T02:10:37.846Z"
  }
}

Book Access by Tier

The sportsbooks included in your odds results depend on your subscription tier:

Tier	Books Available	Included Sportsbooks
Free	2	DraftKings, FanDuel
Hobby	5	+ BetMGM, Caesars, theScore Bet
Pro	15	+ Bet365, BetRivers, and more
Sharp	All 32	All available sportsbooks
Enterprise	All 32	All available sportsbooks

Pinnacle (sharp book) requires Sharp tier or higher. Requesting sportsbook=pinnacle on a Free, Hobby, or Pro tier will return a 403 tier_restricted error.

Filtering Examples


# Get live NBA odds from all your available books
curl "https://api.sharpapi.io/api/v1/odds?league=nba&live=true" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Get moneyline and spread odds for a specific event
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 (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"

Odds Delta - Get only odds that changed since a given timestamp
Best Odds - Get the best odds across all books for each selection
Odds Comparison - Compare odds across books side by side
Batch Odds - Fetch odds for multiple events in one request
Markets - List available market types
Sportsbooks - List available sportsbooks and their status