Odds Snapshot

Get a snapshot of current odds from sportsbooks.

GET /api/v1/odds

AuthenticationPermalink for this section

Requires API key. Available to all tiers.

Query ParametersPermalink for this section

Market Category AliasesPermalink for this section

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.

# 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 (see the note below on scorer markets)
curl "https://api.sharpapi.io/api/v1/odds?league=nba&market=props" \
  -H "X-API-Key: YOUR_API_KEY"

Example RequestsPermalink for this section

curl -X GET "https://api.sharpapi.io/api/v1/odds?league=nba&sportsbook=draftkings&market=moneyline" \
  -H "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;
}

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

PaginationPermalink for this section

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"

Result orderPermalink for this section

Results are returned in chronological order by event start time — events already under way and the soonest to start come first, later ones after. Events with no start time in the feed sort last.

A single page is therefore a slice of the schedule, not a sample across the whole result set. A sportsbook with no games starting inside the stretch of the schedule that page covers will not appear on it, even when it has many matching rows later the same day — that is the expected behaviour, not a gap in coverage. To check whether a book carries a market, filter with ?sportsbook= or narrow with ?league= instead of reading an unfiltered first page.

On a page that has rows, this is what meta.books reports: a book listed in in_scope with no entry in in_page returned no rows on that page — usually because its games fall outside the stretch of the schedule that page covers, not because it is missing the market.

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

ResponsePermalink for this section

Success (200)Permalink for this section

The example below shows the flat fields only. As of May 2026, every row also carries optional nested reference blocks (home, away, sport_ref, league_ref, market_ref, sportsbook_ref) — see Nested reference blocks below.

{
  "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,
      "is_main_line": true,
      "is_alternate_line": false,
      "event_start_time": "2026-01-26T19:00:00Z",
      "timestamp": "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,
      "is_main_line": true,
      "is_alternate_line": false,
      "event_start_time": "2026-01-26T19:00:00Z",
      "timestamp": "2026-01-26T02:10:24.125Z",
      "is_live": false
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 2,
    "has_more": true,
    "next_offset": 50,
    "next_cursor": "eyJlIjoiMzM0ODMxNTMiLCJiIjoiZHJhZnRraW5ncyIsIm0iOiJtb25leWxpbmUiLCJpIjoiZHJhZnRraW5nc18zMzQ4MzE1M19tb25leWxpbmVfUEhJIn0"
  },
  "updated_at": "2026-01-26T02:10:37.846Z"
}

Empty results (200): meta.storePermalink for this section

An empty page — 200 with "data": [] and "count": 0 — can mean two different things: your filters matched nothing, or the serving instance had nothing loaded when it answered (for example, during a store swap). Since September 2026 the response says which. Whenever /odds returns zero rows it adds a meta.store block, and reason is the field to branch on:

{
  "data": [],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 0,
    "has_more": false,
    "next_offset": null
  },
  "updated_at": "2026-09-07T02:41:18.552Z",
  "meta": {
    "store": {
      "generation": 5019,
      "ready": true,
      "books": 39,
      "rows": 810137,
      "reason": "no_match"
    }
  }
}

• Present only on empty results. A response with rows is byte-for-byte unchanged and carries no meta.store; parsers that read data + pagination + updated_at keep working.
• books and rows describe the whole snapshot, not your query — rows: 810137 is evidence that the store was populated, not a count of what you would have matched.
• Queries that resolve to two or more sportsbooks also carry meta.books (the resolved book scope: in_scope and per-book in_page counts); meta.store is added alongside it. So does the empty page of a dashboard book selection that resolved to no book at all — see Empty sportsbook selection below.
• An unknown league or sportsbook value is rejected with 400 invalid_filter rather than answered with an empty page. Other filters are not validated against the catalog: a market_type or event_id that exists nowhere returns an ordinary empty page with reason: "no_match".

Finished events: event_status and completed_atPermalink for this section

A client that keeps polling /odds?event_id=<id> after the game ends gets an authoritative empty page — reason: "no_match" is true, but it does not say why nothing matched. When the page is empty because the one event you filtered on has ended, meta.store says so too. This is the real response for an MLB game that had finished earlier the same night (a single-book query, so the body stays short — a multi-book query carries meta.books alongside, as above):

GET /api/v1/odds?event_id=mlb_twins_whitesox_2026-09-06_b3&sportsbook=pinnacle&limit=1

{
  "data": [],
  "pagination": {
    "limit": 1,
    "offset": 0,
    "count": 0,
    "has_more": false,
    "next_offset": null
  },
  "updated_at": "2026-09-07T10:04:34.951684418Z",
  "meta": {
    "store": {
      "generation": 13456,
      "ready": true,
      "books": 39,
      "rows": 947879,
      "reason": "no_match",
      "event_status": "final",
      "completed_at": "2026-09-07T02:09:37Z"
    }
  }
}

/events/mlb_twins_whitesox_2026-09-06_b3 returned status: "final" with the same completed_at at the same moment — both endpoints read the same record, so they cannot disagree.

The signal is attached only when all of the following hold — otherwise the block keeps its plain shape and neither key is present:

• the request filtered on exactly one event_id (a comma-separated list gets no signal — the field is singular);
• the page is empty with reason: "no_match" (a warming or store_empty page never carries it — the emptiness is the store’s, and reason already says to retry);
• the event is known to have ended. An event that is still live or upcoming, or an id that exists nowhere, gets a plain no_match with no event_status — so a single-id query answered without it means either a wrong id or an event that has not ended.

A finished event whose odds are still cached returns those rows as usual; the signal appears once the page drains. completed_at is the time the completion was detected — typically a few minutes after the event left the live feed — not the final whistle, the same caveat as completed_at on /events. The status code never changes: a client polling an event through its life keeps getting 200.

Empty sportsbook selection: meta.books.reasonPermalink for this section

If the sportsbook selection saved on your dashboard resolves to nothing — every selected book is absent from the current snapshot, or not included in your tier — an unfiltered /odds request is answered with an empty page. The store is fine; the selection is the reason, and the response names it. meta.books — normally present only for queries resolving to two or more sportsbooks — is emitted with an empty scope, reason: "selection_disjoint", and selected, the selection that resolved to nothing (canonical sportsbook IDs, sorted):

{
  "data": [],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 0,
    "has_more": false,
    "next_offset": null
  },
  "updated_at": "2026-09-07T10:04:34.951684418Z",
  "meta": {
    "books": {
      "in_scope": [],
      "in_page": {},
      "reason": "selection_disjoint",
      "selected": ["betano", "bwin"]
    },
    "store": {
      "generation": 13454,
      "ready": true,
      "books": 39,
      "rows": 947919,
      "reason": "no_match"
    }
  }
}

• meta.books.reason takes precedence. meta.store still rides alongside with reason: "no_match" — accurate for the store (it is populated), but not the cause. When meta.books.reason is present, that is why the page is empty; retrying will not change the answer. Fix the selection on your dashboard, or upgrade if the books you selected need a higher tier.
• in_scope and in_page are present and empty ([] / {}, never null). The only reason value today is selection_disjoint.
• Emitted only when the selection is genuinely the cause: the request carried no explicit sportsbook= filter, you have a dashboard selection, and your tier alone would have resolved to at least one book. It never appears on the Free tier (which always serves DraftKings and FanDuel regardless of selection) or on an empty or warming store — those pages are meta.store’s to explain.
• With an explicit sportsbook= filter the same mismatch is rejected instead of answered with an empty page: 403 tier_restricted, 403 book_not_selected, or 503 book_unavailable.
• Pages that resolve to one or more books are unchanged: the two-or-more-book block carries neither reason nor selected, and a single-book scope carries no meta.books at all.

Response HeadersPermalink for this section

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

Error ResponsesPermalink for this section

401 Unauthorized

No key supplied returns missing_api_key; a bad key returns invalid_api_key.

{
  "error": {
    "code": "missing_api_key",
    "message": "API key required. Pass via X-API-Key header, api_key query parameter, or Bearer token.",
    "docs": "https://docs.sharpapi.io/en/authentication#authentication-methods"
  }
}

403 Tier Restricted

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

429 Rate Limited

retry_after is a Unix-millisecond timestamp of when the next window opens (not a duration); the standard Retry-After response header carries the equivalent seconds value.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for pro tier (300/min)",
    "retry_after": 1737853260000,
    "tier": "pro",
    "limit": 300,
    "docs": "https://sharpapi.io/pricing"
  }
}

Odds Object SchemaPermalink for this section

Selection typesPermalink for this section

selection_type carries the canonical side identifier for each selection. Most markets are two-way (e.g. moneyline, point spread, total) and emit one of the simple values below. A small set of multi-axis markets (soccer double-chance, BTTS-combined, result × O/U, MMA round betting, tennis set betting, correct-score, etc.) encode two outcomes per selection and emit compound values joined by _.

Player propsPermalink for this section

On market types whose name starts with player_, a player prop is one row per (player, side, line). Those three axes live in three separate fields, and each has exactly one job:

So the canonical parse is player_name + selection_type + line, and the human label is built by joining them:

{
  "market_type": "player_points",
  "player_name": "Caitlin Clark",
  "selection": "Over",
  "selection_type": "over",
  "line": 21.5,
  "odds_american": -115
}

→ Caitlin Clark Over 21.5 points (-115)

What selection holds on each player-level marketPermalink for this section

is_player_prop: true marks every market priced on one named player. The normalisation above is applied only to the player_* types, so the fields do not read the same way across the whole flagged set. What to expect:

Two things follow for a client:

• selection is not a reliable key across the flagged set. On player_* rows it is the side; elsewhere it is the book’s label. Key on (market_type, player_name, selection_type, line) where player_name is present, and on (market_type, selection) for most_*_player.
• selection_type is other where the market has no direction. On a scorer or most_*_player market there is only one outcome per player — that they score, or that they lead the category — so there is no side to read. Do not treat other as missing data.

New (May 2026): nested reference blocksPermalink for this section

Every odds row now carries six optional nested reference objects that bundle each entity’s slug id, display label, and stable numerical_id directly with the row. The flat string fields (sport, league, home_team, away_team, market_type, sportsbook) remain unchanged — the new blocks are purely additive.

{
  "id": "pinnacle_mlb_yankees_redsox_moneyline_NYY",
  "sportsbook": "pinnacle",
  "sport": "baseball",
  "league": "mlb",
  "home_team": "New York Yankees",
  "away_team": "Boston Red Sox",
  "market_type": "moneyline",
  "selection": "New York Yankees",
  "odds_american": -135,
 
  "home": {
    "id": "new_york_yankees",
    "numerical_id": 20,
    "name": "New York Yankees",
    "abbreviation": "NYY",
    "logo": "https://cdn.sharpapi.io/teams/baseball/20.png",
    "city": "New York",
    "mascot": "Yankees",
    "conference": "AL",
    "division": "East Division"
  },
  "away": {
    "id": "boston_red_sox",
    "numerical_id":  5,
    "name": "Boston Red Sox",
    "abbreviation": "BOS",
    "logo": "https://cdn.sharpapi.io/teams/baseball/5.png",
    "city": "Boston",
    "mascot": "Red Sox",
    "conference": "AL",
    "division": "East Division"
  },
  "sport_ref":      { "id": "baseball", "numerical_id":   3, "name": "Baseball" },
  "league_ref":     { "id": "mlb",      "numerical_id": 354, "label": "MLB" },
  "market_ref":     { "id": "moneyline","numerical_id": 878, "label": "Moneyline" },
  "sportsbook_ref": { "id": "pinnacle", "numerical_id":  28, "label": "Pinnacle" }
}

When fields are absent. Each block is emitted only when the underlying entity is mapped in the SharpAPI atlas and the book’s adapter stamps the reference — coverage is rolling out per book, so rows from some books omit the blocks even for well-known leagues. Unmapped entities (long-tail leagues, niche markets, fresh sportsbook additions) also omit the block, in which case the flat field on the row is the only ID you’ll see. Treat every block — and every inner field, including numerical_id and abbreviation — as optional.

See Entity reference IDs for the full semantics, the dense-from-1 / frozen / never-reused contract, and recommended use cases (storage keys, cross-feed mapping, display labels).

Event-Grouped ResponsePermalink for this section

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": "nba_76ers_suns_2026-01-26_b3",
      "event_name": "PHO Suns @ PHI 76ers",
      "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,
          "timestamp": "2026-01-26T02:10:24.125Z"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 1,
    "total": 1,
    "has_more": false,
    "next_offset": null
  },
  "updated_at": "2026-01-26T02:10:37.846Z"
}

Asian Markets (Soccer)Permalink for this section

Asian handicap and quarter-goal totals are carried, but they do not all arrive under a single market_type. One book can price the same Asian handicap under two different types, and two books can normalize it differently, so filtering on one exact type silently drops the rest — you get a short list or an empty array and no error.

Use a category alias, not an exact market type:

# Every handicap shape, all normalizations, one request
curl "https://api.sharpapi.io/api/v1/odds?sport=soccer&market=spread" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Goal totals, including quarter-goal and Asian total lines
curl "https://api.sharpapi.io/api/v1/odds?sport=soccer&market=total" \
  -H "X-API-Key: YOUR_API_KEY"

Market name mappingPermalink for this section

Telling an Asian handicap from a European onePermalink for this section

An asian_handicap or point_spread row on soccer arrives as exactly two rows per book and line — selection_type home and away, never draw. (market=spread also returns three_way_handicap, which does have a third leg; that type is labelled separately, so the market_type tells you which shape you have.) Within the two-row types, the line is what separates Asian from European:

• Quarter lines (-0.25, -0.75, -1.25, -1.75) are Asian handicaps. No European handicap is priced at a quarter goal.
• Whole and half lines (-1, -1.5) can be either.

Quarter lines are not roundedPermalink for this section

line is a JSON number at the precision the book priced it. A -0.25 handicap comes back as -0.25; it is not collapsed into -0.5 or 0:

{
  "market_type": "asian_handicap",
  "selection": "Burgess Hill Town FC",
  "selection_type": "home",
  "line": -0.75,
  "odds_decimal": 2.68
}

Each distinct line is its own set of rows, so -0.25 and -0.5 on the same event are two separate prices — not one price you have to un-round. The same holds for quarter-goal totals (2.25, 2.75, 3.25 under total_goals and asian_total_goals).

Book Access by TierPermalink for this section

The sportsbooks included in your odds results depend on your subscription tier. A book’s own minimum tier is the requires_tier field on GET /api/v1/sportsbooks.

The Sportsbooks page carries the full per-book list, generated from the live catalogue — use it rather than this summary when you need to know whether one specific book is in reach.

Filtering ExamplesPermalink for this section

# Get live NBA odds from all your available books
curl "https://api.sharpapi.io/api/v1/odds?league=nba&is_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_id=nba_76ers_suns_2026-01-26_b3&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"

FuturesPermalink for this section

Futures markets — season-long props, outrights, championship winners, and similar — are excluded from this endpoint by default. Add ?include_futures=true to include them.

include_futures=true also applies to Odds Comparison and Batch Odds (as a request body field) with the same semantics.

Related EndpointsPermalink for this section

• 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