ParlayAPI Documentation

Real-time sports odds API: 30+ sources in a single call, 6× cheaper than the-odds-api. Drop-in compatible with TOA's URL surface where it makes sense, with extensions for player props, prediction-market exchanges, and WebSocket streaming.

Quick Start

Start with a request below, or use the step-by-step guide for key setup, response checks, and troubleshooting. For complete runnable examples, see the language quickstarts.

pip install parlay-api

from parlay_api import ParlayAPI
client = ParlayAPI(api_key="YOUR_KEY")
odds = client.odds("baseball_mlb", regions="us")

curl "https://parlay-api.com/v1/sports/baseball_mlb/odds?regions=us" \
  -H "X-API-Key: YOUR_KEY"

const r = await fetch(
  "https://parlay-api.com/v1/sports/baseball_mlb/odds?regions=us",
  { headers: { "X-API-Key": "YOUR_KEY" } }
);
const odds = await r.json();

import requests
r = requests.get(
    "https://parlay-api.com/v1/sports/baseball_mlb/odds",
    headers={"X-API-Key": "YOUR_KEY"},
    params={"regions": "us"},
)
odds = r.json()

Authentication

Pass your API key one of two ways:

• Header: X-API-Key: YOUR_KEY (recommended)
• Query param: ?apiKey=YOUR_KEY (TOA-compatible)

WebSocket connections use the query param: wss://parlay-api.com/ws/odds/{sport_key}?apiKey=YOUR_KEY

Credits & Pricing

Most paid endpoints deduct a fixed number of credits per call. Multi-market endpoints such as /odds, /clv/history, and /sgp/price use the formulas in /v1/meta/credit-costs. One /props call returns ALL books for that sport.

Tiers

Concurrent SSE/WS = max simultaneous push-stream connections per API key. Polling endpoints aren't connection-capped, only credit-capped. Hit the limit and new SSE / WS connections return 429 / WS close 4002 with a clear reason; existing connections aren't affected. The full odds feed (/ws/odds/{key}, /v1/sse/odds/{key}) requires Business tier or above; Starter and Pro only reach the narrower in-play play-by-play stream (/v1/sports/{key}/live/sse, row above) within their connection cap.

Sandbox (no auth, fake data)

Hit /v1/sandbox/sports, /v1/sandbox/sports/{sport_key}/odds, /v1/sandbox/sports/{sport_key}/live/period_markets, or /v1/sandbox/sports/{sport_key}/live/sse to see the response shape with deterministic synthetic data. No API key, no credits consumed, IP rate-limited at 60 req/min. Useful for verifying integration shape during off-hours when no real games are live.

Source health diagnostic

Live-betting bots need to know when a source goes stale so they don't trade on dead data. GET /v1/sports/{sport_key}/live/source-health?apiKey=YOUR_KEY returns per-source freshness for the requested sport (events in the last 5 min, seconds since last event, latest capture timestamp). 1 credit per call. Recommended polling cadence: 30 seconds. A source with seconds_since_last_event > 60 during a known-live game has likely failed; failover yourself or rely on our internal failover (one source going down doesn't break customer SSE, primary auto-promotes).

Postman + OpenAPI spec

Full machine-readable OpenAPI spec at /openapi.json (190+ paths). Postman supports importing OpenAPI directly: Postman → Import → Link → paste the URL above → Import. Auto-generated collection with every endpoint pre-populated.

SDKs and language quickstarts

Python: python -m pip install parlay-api==0.3.2 · verified PyPI release · public source.

JavaScript / Node: start with the native fetch quickstart, which needs no package install. The JavaScript SDK source is public; source availability does not establish an npm release.

All eight language quickstarts include setup, a first request, and empty-response handling. Check the published SDK version's features before relying on retry helpers or streaming support.

API stability

Read the full versioning + deprecation policy. Short version: paths under /v1/ are stable. Additive changes ship without notice. Breaking changes ship under /v2/ with 12+ months of overlap. Pricing changes get 30+ days of notice. Your integration won't break overnight.

Every response includes x-requests-used, x-requests-remaining, and x-requests-last headers so you always know how much you've burned. Empty responses still bill normally (no auto-refund, see the leak fix if curious).

Python SDK

Pure-Python single-file SDK on PyPI: pip install parlay-api. Source on GitHub.

The SDK is a near drop-in replacement for the-odds-api's official Python clients with extra methods for our extensions and built-in devig math helpers.

from parlay_api import ParlayAPI

client = ParlayAPI(api_key="YOUR_KEY")

# TOA-compatible methods
sports = client.sports()
events = client.events("baseball_mlb")
odds = client.odds("baseball_mlb", regions="us", markets=["h2h", "spreads"])
historical = client.historical_odds("baseball_mlb", date="2024-10-15")

# Extensions
props = client.props("baseball_mlb", markets=["player_total_bases"])
arbs = client.arbitrage("baseball_mlb", limit=20)
consensus = client.consensus("baseball_mlb")

# Devig math (no network call)
fair_over, fair_under = ParlayAPI.devig(over_price=-110, under_price=-110)
edge_pct = ParlayAPI.edge(book_price=-105, fair_prob=fair_over)

# WebSocket URL builder
ws_url = client.websocket_url("baseball_mlb")

Sports

List all sport keys with at least one event in the last 24 hours.

Response

[
  {
    "key": "baseball_mlb",
    "group": "Baseball",
    "title": "MLB",
    "description": "Major League Baseball",
    "active": true,
    "has_outrights": false
  },
  ...
]

See Sport Keys reference for the full list.

Events

List events for a sport. Deduped by canonical_event_id (an MD5 of sport + date + sorted team names) so the same matchup from books with different team naming conventions ("NY Yankees" vs "New York Yankees") collapses into one event.

Parameters

Response

[
  {
    "id": "8b1f3a2c0e9d4...",
    "canonical_event_id": "ee78855a3bdd1019",
    "sport_key": "baseball_mlb",
    "sport_title": "MLB",
    "commence_time": "2026-05-01T19:35:00Z",
    "home_team": "New York Yankees",
    "away_team": "Kansas City Royals"
  },
  ...
]

Odds

TOA-compatible game-line odds. Returns moneyline, spread, totals (and player_* markets if you ask for them) across every book that publishes them.

You are only charged for markets this endpoint can serve. The price is markets x regions, so a key we cannot serve used to cost the same as one we can and then be dropped from the response. Since 2026-09-05 (ticket #295) such a key is dropped from the multiplier instead: the request is still answered exactly as before (a valid derived market never 400s here, so a migrating pipeline is never aborted mid-run) and the key costs nothing. Every charged response carries x-markets-served, the market keys the charge covered; anything we cannot serve here comes back in x-markets-unservable (billed zero) with the endpoint that owns it in x-markets-served-elsewhere. A servable key that no book is pricing right now still costs a credit and still appears in x-markets-served: that is coverage, not a gap.

Both sides of a two-way price always come from the same fixture, and from the same phase of it. When the same two teams or players meet twice in a day, each meeting is priced only from what a book posted for that meeting. A side that book has not posted for this fixture comes back with a null price rather than being filled from another match, so a null price is an absent quote and never a value we worked out for you.

Parameters

Repeating a list parameter is the same as the comma form. ?markets=h2h&markets=spreads and ?markets=h2h,spreads are one request and are billed identically: you get the union, not the last occurrence. This holds for markets, bookmakers and regions on every endpoint that takes them, REST, SSE and WebSocket alike. A value repeated across occurrences is counted once, so ?regions=us&regions=us costs one region.

Example

odds = client.odds(
    "baseball_mlb",
    regions="us",
    markets=["h2h", "spreads", "totals"],
    bookmakers=["draftkings", "fanduel", "pinnacle"],
)

curl "https://parlay-api.com/v1/sports/baseball_mlb/odds?regions=us&markets=h2h,spreads,totals&bookmakers=draftkings,fanduel,pinnacle" \
  -H "X-API-Key: YOUR_KEY"

Every event and row that carries commence_time also carries commence_time_reported. It is true when a source reported the start time you are reading, and false when no source did, in which case commence_time is null. We never fill a missing kickoff with a guess. Events with a null start time are still served, because their prices are real, but they are left out of any window you ask for with commenceTimeFrom, commenceTimeTo, date or live=true, since the question cannot be answered for them. Call the same endpoint without those parameters to see them. Outrights and futures are the exception: markets=outrights events are markets rather than fixtures, they never have a kickoff, and they are returned whether or not you narrow the board. Treat commence_time as nullable in every parser, on /odds, /events, /props, /scores and the historical endpoints alike.

Every bookmaker block carries stale_seconds and last_update_ms, and both describe the OLDEST price in that block, so a fresh price on one side of a market never dates a stale one on the other. A book whose last price for a fixture is older than our 10 minute window is re-served for up to one hour; past that the book is left out of that market instead of being served as current. A block that came from that re-serve is marked "topped_up": true, so you can tell a re-served last price from a fresh write. The mark is on the block, so it covers every market listed under that bookmaker.

Player Props

Player prop odds across every book in one call. Each row has over_price, under_price, line, and the bookmaker source. Includes the standard sportsbooks plus DFS apps (PrizePicks, Underdog, Betr, Sleeper, Pick6) and exchange data (Novig, Kalshi).

Parameters

Response shape

[
  {
    "bookmaker": "draftkings",
    "bookmaker_title": "DraftKings",
    "player": "Aaron Judge",
    "market_key": "player_home_runs",
    "market": "Home Runs",
    "line": 0.5,
    "over_price": 290,
    "under_price": -370,
    "home_team": "New York Yankees",
    "away_team": "Kansas City Royals",
    "canonical_event_id": "ee78855a3bdd1019",
    "commence_time": "2026-05-01T19:35:00Z",
    "last_update": 1746130000000,
    "age_seconds": 3
  },
  ...
]

Every row carries age_seconds, the real age of that book's latest observation. Props serve the latest row per book from the last 60 minutes, so use ?maxAgeSec=N to bound freshness on quiet markets.

Injury object

Rows for a player who has a current ESPN injury record also carry an injury object. Sourced from ESPN's public feed and rebuilt every 10 minutes, covering MLB, NBA, WNBA, NHL, NFL and NCAAF. A player with no record has no injury key, which normally means healthy.

"injury": {
  "status": "Out",
  "description": "Haulcy (ankle) did not participate in Tuesday's practice.",
  "date": "2026-09-01T23:18Z",
  "team": "Indianapolis Colts",
  "team_abbr": "IND",
  "il_category": "O",
  "body_part": "Ankle",
  "side": "Left",
  "position": "S",
  "expected_return": "2026-09-13",
  "updated_at": "2026-09-05T19:47:00Z"
}

description is ESPN's short comment, falling back to the injury detail string, and a detail that is only ESPN's Not Specified placeholder counts as absent. The cache is rebuilt every 10 minutes and its size tracks the injury report, so this is a proportion and not a fixed count: about 97% of records carry a description (830 of 858 on the 2026-09-05 prod cache). The rest have nothing to say and the field is null rather than filled in. The raw detail is still served verbatim by the /injuries endpoints. team and team_abbr are resolved from ESPN's own team id and are null for an id outside the leagues above; no team is ever borrowed from another league. The same record is served in full by /v1/sports/{sport_key}/injuries.

Line Movement

Time-series price history for one event, grouped into a series per (source, player, market_key, line). Use it for CLV and steam detection.

Parameters

Player-keyed books (PrizePicks, and the teamless tail of every other book)

PrizePicks props are keyed by player, not by fixture: in a one-hour prod sample every PrizePicks row carried no team at all, 34,911 of 34,911. Sleeper, Underdog, Betr, Pinnacle, DraftKings and Caesars each write a smaller teamless tail as well. Those series are resolved by player_name + market_key + sport_key + game_date, the same identity /props publishes them under, so the canonical_event_id you read off a PrizePicks /props row works here directly.

Each series says how it was resolved. matched_by: "team" means the book stated the fixture and home_team/away_team are that fixture. matched_by: "player" means the book stated only the player, and the team fields are empty strings, exactly as /props serves them. A team is never inferred onto a player-keyed row.

Two limits of matching on a player. The identity available on a teamless row is (sport_key, game_date, player_name) and nothing else, so two athletes who share a name on the same slate cannot be separated: their observations arrive as one series. Nothing is fabricated when that happens - the series still carries matched_by: "player" and empty team fields - but it is a grouping, not a stated fixture. And when you ask with a team-keyed eventId, the companion player lane looks up at most the first 300 player names (alphabetically) found in that event's team-keyed rows. Passing player sidesteps both.

Grouping, and books that quote no price

A series is one (source, player, market_key, line). A book that moves its line therefore produces one series per line rather than a single series showing the move; read the moves off the series' time ranges. over_movement describes the price at a fixed line, not the line itself.

PrizePicks and Betr quote no price at all - 0 of 34,982 PrizePicks rows and 0 of 8,657 Betr rows carried an over price in a one-hour prod sample - so their series come back with over_price, under_price, opening_over, current_over and over_movement all null, and everything they moved is in line. Underdog and Sleeper do carry prices. /props normalizes DFS flat payouts to +100/-100 for comparability; this endpoint serves the raw row, so the two differ by design.

Limits, stated plainly

• Live table only, for every book. This endpoint reads prop_snapshots, the live table, which holds roughly the last 6.5 hours, so hours=168 is accepted and clamped by the data rather than by an error. Resolving a player-keyed eventId searches that same window, so a book that pulled its slate hours ago still resolves. Older prices live in /closing-odds, which is a closing line per market and not a movement series. For PrizePicks and Betr not even that exists: they hold 0 rows in the closing archive (of 40,594,128), so a PrizePicks series older than the live table is not available from any endpoint. Underdog (1,336,439 rows) and Sleeper (46,231) are archived. Measured on prod 2026-09-05.
• 5,000-row cap per request. The series query returns at most 5,000 rows, most recent first. Every response carries X-Line-Movement-Row-Cap, and X-Line-Movement-Truncated: 1 when the cap actually bound. When it binds, the response covers only the most recent 5,000 rows of your window and opening_over is the oldest price in that slice, not the true open. It binds on the busiest events (275 of 7,072 team-keyed events over a 24-hour lookback in a prod sample); a player or market filter avoids it.
• Single-snapshot series are dropped. A series needs at least 2 observations to describe movement, so a book that quoted a price once and never moved it does not appear.

Response shape

[
  {
    "event_id": "18c52d6b8b8a0937",
    "home_team": "",
    "away_team": "",
    "matched_by": "player",
    "source": "prizepicks",
    "player": "A.J. Brown",
    "market_key": "player_receiving_yards",
    "line": 62.5,
    "snapshots": [{"timestamp_ms": 1757100000000, "time": "2026-09-05T17:20:00+00:00", "over_price": 100, "under_price": -100, "line": 62.5}, ...],
    "count": 14,
    "opening_over": 100,
    "current_over": 100,
    "over_movement": 0,
    "opening_under": -100,
    "current_under": -100,
    "hours_tracked": 3.4
  },
  ...
]

An empty result is returned as an object, not an array: {movements: [], count: 0, event_id, sport_key, row_cap, min_snapshots_per_series, filters, note}, where note names the reasons it can be empty. That holds on every empty path, including an eventId that resolves to nothing, and it does not change between a cache miss and the cache hit behind it. The two X-Line-Movement-* headers are on empty responses too.

Consensus

For each unique (event, player, market, line), returns the best and worst price across all books, the average consensus price and implied probability (as a percent), and the spread between them. Useful for line-shopping. DFS books are excluded from the math. Moneyline consensus is included - pass markets=h2h for the per-side consensus moneyline of each game (market_key h2h, or h2h_3_way with a Draw side for soccer).

Response per row

{
  "canonical_event_id": "ee78855a3bdd1019",
  "home_team": "New York Yankees", "away_team": "Kansas City Royals",
  "player": "Aaron Judge", "market_key": "player_home_runs", "line": 0.5,
  "num_books": 4, "total_books": 4,
  "consensus_odds": 290, "consensus_prob": 25.6,
  "best_odds": {"bookmaker": "fliff", "price": 310},
  "worst_odds": {"bookmaker": "draftkings", "price": 270},
  "spread": 40,
  "all_books": [
    {"bookmaker": "fliff", "price": 310},
    {"bookmaker": "fanduel", "price": 295},
    ...
  ]
}

Arbitrage

Two-leg arbs across books on the same prop, with optimal stake split and projected profit. DFS books excluded. Profit cap 15% (anything higher is almost certainly stale or mis-paired data).

Parameters

+EV Picks

Bets where one book's price implies a higher win probability than a "fair" baseline (Pinnacle de-vigged, with Novig as an exchange-priced cross-check). Returns book, line, edge percentage, and Kelly-optimal stake.

Live Games

Currently in-progress games with grouped book quotes. Sub-10s freshness on our in-play collectors.

Live Point-by-Point (PBP)

Real-time match-state events. Covers tennis, baseball (MLB), basketball (NBA), hockey (NHL), MMA (UFC), boxing, NFL, and soccer (Premier League, La Liga, Bundesliga, Serie A, Ligue 1, UEFA Champions / Europa, MLS). Cross-source redundancy: when our primary feed for a sport drops, a fallback (ESPN / SofaScore) auto-promotes within 30 seconds.

Snapshot (polling)

Returns current state for one match (with match_id) or all in-play matches for the sport (omit match_id). Free tier OK.

Parameters

Stream (Server-Sent Events)

Persistent SSE connection. Server pushes each state change (point won, game won, set closed, goal, foul, pitch outcome, period change) within ~50ms of the event. Starter+ tier required. Use the standard EventSource API.

The connection charge covers the initial snapshot plus streaming. Reconnects are billed as new connections.

// JS
const es = new EventSource('https://parlay-api.com/v1/sports/tennis/live/sse?match_id=...&apiKey=...');
es.addEventListener('initial_state', e => console.log('snap', JSON.parse(e.data)));
es.addEventListener('pbp_event', e => console.log('event', JSON.parse(e.data)));

Cross-book latency

Per-book lag relative to our primary PBP feed. Returns each book's effective latency in seconds. Pro+ tier. Use case: arb scanners check this every few seconds and flag matches where a specific book has stale lines (positive lag > 5s typically means an exploitable window).

{
  "sport_key": "baseball_mlb",
  "results": [
    {"match": "Yankees vs Rangers", "book": "fanduel",   "lag_seconds": 7.8, ...},
    {"match": "Yankees vs Rangers", "book": "draftkings","lag_seconds": 1.2, ...},
    {"match": "Yankees vs Rangers", "book": "caesars",   "lag_seconds": 4.0, ...}
  ]
}

Period markets (1H, Q1-Q4, halves, NHL periods)

In-game spreads, totals, and h2h for sub-game periods: 1st half, 2nd half, quarters (NBA, WNBA, NFL, NCAAF), hockey periods (NHL), or first 5 / first 7 innings (MLB). Includes alternate lines: a single Q1 spread query for one NBA game returns ~8 to 10 alt lines. Open to all tiers (Free can run ~500 test calls; continuous high-frequency polling needs Pro or Business). Latency: 1 to 4 seconds (vs 30s+ on the-odds-api).

Query params: period (FT, 1H, 2H, Q1, Q2, Q3, Q4, OT, P1, P2, P3, F5, F7, or 'all'), match_id, source, market (spread, total, h2h). All optional except apiKey.

GET /v1/sports/basketball_nba/live/period_markets?period=Q1&market=spread&apiKey=...

{
  "sport_key": "basketball_nba",
  "period": "Q1",
  "market": "spread",
  "count": 18,
  "results": [
    {"source":"pinnacle", "home_team":"Oklahoma City Thunder",
     "away_team":"Los Angeles Lakers", "period_key":"Q1",
     "market":"spread", "side":"home", "line":-3.5, "price":-144,
     "age_seconds":1, ...},
    {"source":"pinnacle", "side":"away", "line":3.5, "price":120, ...},
    ...alt lines from -2.5 through -6.0...
  ]
}

GET /v1/sports/{sport_key}/live/period_markets/sources returns which books have which periods active right now (last 10 min). Useful for client-side discovery.

Sports with period coverage: NBA (1H, 2H, Q1-Q4), WNBA (1H, 2H, Q1-Q4), NCAAB (1H, 2H), NFL (1H, 2H, Q1-Q4), NCAAF (1H, 2H, Q1-Q4), NHL (P1, P2, P3), MLB (F5, F7), soccer leagues (1H, 2H). Coverage depends on book availability per period; e.g. Pinnacle has every period for every sport, DraftKings/FanDuel/BetMGM/Caesars vary by league.

In-Play Arbitrage Scanner

Cross-book arbs detected during live games. Updated every 5 seconds. Pairs with the WebSocket: subscribers receive {"type":"arb_flagged"} frames the moment a new arb is found.

Player Ratings (market implied)

A strength rating for each player in a 1v1 sport, derived from the market rather than from results. Supported today for table_tennis and its sub leagues, where we hold paired moneylines from Bovada and Tenbet.

What the number is. For every fixture we take the last price each book posted before the listed start time, remove the vig from the two sides, and fit an iterative Elo to those probabilities. So the rating answers "who did the market think was stronger, before a ball was struck".

What the number is not. It is not an official ITTF or WTT ranking. It is not a results rating and it is not a prediction. Any price quoted at or after the start time is an in play price and is excluded, because an in play price mostly encodes who is currently ahead. rating and implied_win_rate are derived numbers, computed by ParlayAPI from book prices.

Selection rules, all reported back in the response. A fixture is keyed by home player, away player and start time, so the same two players meeting twice in one day counts as two fixtures and neither borrows the other's price. Both sides must have a pregame price or the fixture is dropped. The two implied probabilities must sum to a plausible book total (0.98 to 1.30) or the fixture is dropped. One fixture counts once no matter how many books priced it. A book names the side either on its own ("Adam Svoboda") or inside a compound market label ("Adam Svoboda v Vaclav Dolezal · Match Winner · Adam Svoboda"); both are read, and the trailing name must match a side exactly.

Query params: limit (1 to 500, default 100), min_matches (1 to 50, default 3), window_days (1 to 180, default 30). Coverage is limited by how many pregame prices we hold, so matches_used is normally far smaller than the number of fixtures in the window; the response says exactly how many were dropped and why.

GET /v1/sports/table_tennis/player-ratings?window_days=30&min_matches=3&apiKey=...

{
  "sport_key": "table_tennis",
  "rating_kind": "market_implied",
  "rating_basis": "pregame_closing_lines",
  "rating_method": "iterative_elo_from_devigged_pregame_closing_moneylines",
  "window_days": 30,
  "data_window_start": "2026-08-06T06:00:00Z",
  "data_window_end": "2026-09-05T02:05:00Z",
  "min_matches": 3,
  "total_rated_players": 1036,
  "matches_used": 8750,
  "matches_dropped_inplay_only": 17259,
  "matches_dropped_one_sided": 71,
  "matches_dropped_implied_total_out_of_range": 0,
  "matches_priced_by_multiple_books": 168,
  "implied_total_bounds": [0.98, 1.3],
  "source_matches": 8750,
  "ratings": [
    {"player": "Andrew Baggaley", "rating": 1662.8, "matches": 9,
     "implied_win_rate": 0.7092, "last_match_at": "2026-08-21T14:35:00Z"},
    ...
  ]
}

Field notes: matches_used is the number of fixtures behind the ratings. matches_dropped_inplay_only counts fixtures for which we hold a match winner price named to a side, but every such price was quoted at or after the start; fixtures we hold no named match winner price for are not counted here at all. matches_dropped_one_sided counts fixtures where only one player had a pregame price. data_window_start and data_window_end are the first and last fixture actually used, which can be narrower than window_days. last_match_at is that player's most recent used fixture. source_matches is retained as an alias of matches_used.

Historical Odds

Historical is split by product shape so modelers can tell prices from results. We do not derive or invent missing odds.

/v1/historical/sports/{sport_key}/odds takes markets= and charges 10 x markets x regions. It serves h2h, spreads and totals and nothing else: the archive it reads has moneyline, spread and total columns, so there is no alt ladder, no outrights and no props in it. Any other key is answered but billed zero and named in x-markets-unservable. Prop history lives at /v1/historical/sports/{sport_key}/closing-odds?markets=<key> and period-market history at /v1/historical/sports/{sport_key}/period_markets; outrights and the alt ladder are live-only, on /v1/sports/{sport_key}/odds.

A retired book (an operator that has closed, currently maverick_games, closed 2026-09-01) is refused on every live endpoint but its closing lines captured while it was open stay queryable here and on the closing-line and bulk export endpoints, and each of its rows carries "retired": true with the closed_on date (the CSV export carries the same two facts as trailing columns). Games dated after the closure are not served for it: the book never closed them.

Esports note: CS2, Dota 2, and Valorant have historical match/result archives plus current forward Pinnacle price capture. They do not yet have deep historical before/during/after odds movement for past years.

Parameters

Exchanges

Exchange-specific data including order book depth where available. Currently novig.

Event Market Search

Free-text discovery across Kalshi, Polymarket, and Novig event markets. Built for Specials, next-team markets, coach-out markets, trade deadline markets, and other non-standard contracts that do not fit a fixed sport/event schema.

Try the live demo at /event-markets.

Parameters

Example

curl 'https://parlay-api.com/v1/event-markets/search?q=AJ%20Brown%20next%20team&sources=kalshi,novig,polymarket&min_volume=1000'

Response highlights

{
  "query": "AJ Brown next team",
  "credits_charged": 0,
  "source_summary": {
    "kalshi": {"count": 10, "max_volume": 283989.29},
    "novig": {"count": 4, "max_volume": 9458.94}
  },
  "markets": [
    {
      "source": "kalshi",
      "event_title": "A.J. Brown's Next Team",
      "outcome": "New England",
      "prices": {"yes_bid": 0.79, "yes_ask": 0.81}
    }
  ],
  "clusters": [
    {
      "cluster_key": "aj brown next team",
      "sources": ["kalshi", "novig"],
      "note": "Candidate text match only. Prices remain source-native and are not blended."
    }
  ]
}

WebSocket: /ws/odds

Real-time odds streaming for one sport. Business / Enterprise / Scale tier required. Receives a JSON frame the moment a price changes anywhere in our collector pipeline.

Authentication

Every WebSocket route takes the key in any of these three forms. /ws/odds and /ws/live share one auth path, so a key that opens one opens the other, and both refuse with the same close codes.

A logged-in dashboard session cookie is a credential on /ws/live only, which is the free live board's own feed. The metered sockets (/ws/odds, /ws/odds-fast) need a key in one of the forms above, whatever browser they are opened from: the credit allowance is metered per key, and a cookie carries none. When both a key and a session cookie are present, the key wins.

Close codes on a refused connect are the same on every WebSocket route: 4003 no key on the request, 1008 key not valid, 4001 tier below Business (or an expired session), 4002 concurrent-connection cap, 4004 monthly credits spent. A refused connect is never billed.

Query params

The initial_state frame is filled per book

The row budget set by limit is a fair allocation among the books the fetch returned, not a newest-first fill. Books draw rows in turn until the budget is spent, game lines before props within each book and freshest fixture first. Sharp books such as Pinnacle publish a great many rows on their own cadence; before this, a ten-book subscription could receive 500 rows of one book and meet the other nine only in later odds_update frames.

It is an allocation, not a coverage guarantee. The fill shares out what this connect's fetch came back with, so a book can still be thin or absent from the frame. The per-book numbers below describe this build only: they are what this one snapshot held after its own filters and what it served, and they say nothing about your account, the sport, or your next connect.

The frame says what it contains and what it left out:

{"type": "initial_state", "sport_key": "americanfootball_nfl",
 "count": 500, "snapshot_limit": 500, "snapshot_fill": "per_book",
 "books": ["betmgm", "bovada", "caesars", "draftkings", "fanduel",
           "novig", "pinnacle", ...],
 "truncated": true,
 "truncated_books": {"pinnacle": {"served": 320, "omitted": 4680}},
 "data": [ ... ]}

A book listed in truncated_books with a non-zero served is in data; one listed with served 0 is not, and does not appear in books either. A book in missing_books is a different case again: that field only appears on a partial frame, where a book's snapshot could not be read at all and the stream was served without it rather than refused.

There is no guarantee of eventual delivery of the omitted rows. An odds_update frame is sent when a row changes, so a line that does not move may never be pushed on this connection. If you need those rows in hand, raise limit, narrow bookmakers / markets / kinds, or read them from /v1/odds.

What the fill does not touch: the merged selector, the native current page and stream lifecycle behaviour are unchanged. Your limit carries into the re-attach, so a connection served a partial frame and re-attached later is filled at the same budget it asked for on connect.

Frame types

Filter to one game

Send a subscribe frame after connect:

{"type": "subscribe", "event_id": "ee78855a3bdd1019"}

To unsubscribe and receive sport-wide updates again:

{"type": "unsubscribe"}

Python example

from parlay_api import ParlayAPI
import asyncio, json
import websockets

async def stream():
    client = ParlayAPI(api_key="YOUR_KEY")
    url = client.websocket_url("baseball_mlb")
    async with websockets.connect(url) as ws:
        async for raw in ws:
            frame = json.loads(raw)
            if frame["type"] == "odds_update":
                for row in frame["data"]:
                    print(row["bookmaker"], row["player"],
                          row["over_price"], row["under_price"])

asyncio.run(stream())

End-to-end delivery latency: 300-800 ms on Scale (raw), up to the tier coalesce window otherwise (Business 1 s, Enterprise 0.5 s). Source cadence varies by book and market.

Row freshness: last_update, price_age_s and line_changed_at_ms

Every streamed row carries last_update (epoch milliseconds we last wrote or re-verified that price) and price_age_s, a server-computed convenience field with no client clock-skew guesswork. price_age_s is the seconds since the price last actually MOVED, not since the last write: when a book re-emits an unchanged price as a verification write, last_update advances but price_age_s keeps counting from the real move, so a frozen line never reads as fresh. The row also carries line_changed_at_ms, the epoch milliseconds of that last real move, if you want to compute the age yourself. Sharp books such as Pinnacle update on their own slower cadence, so a larger price_age_s there is real, not stale.

To protect live in-play consumers, a fast book's line that has stayed frozen for more than about 150 seconds during a commenced game is dropped from the live feed rather than streamed with a fresh-looking timestamp, so the socket agrees with /live. Read price_age_s if you want to enforce your own tighter or looser staleness cutoff.

SSE Hot Feed: /v1/sse/hot

EventSource-compatible HTTP stream for enterprise hot paths. It sends a connection frame, source freshness, initial state, then live updates with a 5-second heartbeat.

Filters

The initial_state frame here is the same frame /ws/odds sends, built by the same code and filled per book: see The initial_state frame is filled per book above for books, snapshot_fill and truncated_books. Requesting the same params on either transport returns the same rows.

const es = new EventSource(
  "https://parlay-api.com/v1/sse/hot/baseball_mlb?apiKey=YOUR_KEY&bookmakers=fanduel,pinnacle&kinds=game&heartbeat_s=5"
);

es.onmessage = (ev) => {
  const msg = JSON.parse(ev.data);
  if (msg.type === "odds_update") console.log(msg.data);
};

# Python quickstart
import json, requests

url = "https://parlay-api.com/v1/sse/hot/baseball_mlb"
params = {
    "apiKey": "YOUR_KEY",
    "bookmakers": "fanduel,pinnacle",
    "kinds": "game",
    "heartbeat_s": 5,
}

with requests.get(url, params=params, stream=True, timeout=60) as r:
    r.raise_for_status()
    for line in r.iter_lines(decode_unicode=True):
        if line and line.startswith("data: "):
            msg = json.loads(line[6:])
            if msg["type"] in ("hot_feed_status", "odds_update"):
                print(msg)

Hot feed means fast delivery once a book update lands in our pipeline. It does not invent prices or promise that every external book publishes a new price every 5 seconds.

Operational check: admins run python3 scripts/verify_book_coverage.py before broad outreach or deploys to prove active books survive REST and SSE visibility.

WebSocket: /ws/live

The feed behind our own live board: game lines for one sport, plus the moneylines the board overlays onto each game card. It is a narrower feed than /ws/odds, not a live-only view of it. For spreads, totals, player props and alternate lines, use /ws/odds and read commence_time to pick out the games already under way.

Auth is identical to /ws/odds: the X-API-Key header, ?apiKey=, or ?api_key=, on a Business / Enterprise / Scale key. See Authentication above. The live dashboard opens this same socket with its session cookie, which is why a logged-in browser needs no key; this is the one route where the cookie is a credential.

Three protocol differences from /ws/odds, worth knowing before porting a client:

• No initial_state frame. You get {"type":"connected", ...} and then odds_update diffs, so build your baseline from GET /v1/odds first, or use /ws/odds, which does send one.
• No query filters. bookmakers, markets, kinds, diff, since, event_id and max_age_s belong to /ws/odds; on this route they are ignored rather than applied.
• The board payload is a property of the route, not of your credential: a Business key gets the same rows the dashboard cookie gets. Send {"type":"subscribe","event_id":"..."} to lock to one game, and that game arrives in full, which is what the board's game modal uses.

This route used to accept the dashboard cookie and nothing else, so an API key was closed with 4001 "Not logged in" no matter which form it arrived in. Fixed 2026-09-05. If you worked around it by polling, you can go back to the socket.

Errors & Status Codes

The Python SDK raises typed exceptions: InvalidAPIKeyError, CreditLimitExceededError, RateLimitedError, TierGatedError, all subclasses of ParlayAPIError.

Sport Keys

Live keys (those with active events in the last 24h). The /v1/sports endpoint returns the current authoritative list.

The table above is the headline subset, not the catalogue. GET /v1/sports serves 90+ keys in total, including the regional soccer, basketball, baseball and hockey leagues carried via Pinnacle, and it is the authoritative list and the authoritative count.

How league keys are named

Beyond the marquee leagues above, a key follows the pattern <sport>_<league>: the league's own name, lowercased, with spaces and separators collapsed to underscores. For example, Pinnacle's "Puerto Rico - Superior Nacional" is basketball_puerto_rico_superior_nacional, "Argentina - Torneo Federal" is basketball_argentina_torneo_federal, "Brazil - Paulista FPB U20" is basketball_brazil_paulista_fpb_u20, and "Lebanon - Lebanese Basketball League" is basketball_lebanon_lebanese_basketball_league.

Basketball is covered in full: every league Pinnacle carries is ingested automatically under its own key, from the majors (basketball_nba, basketball_wnba, basketball_ncaab) through the European competitions and every regional, women's and developmental league on offer. A new league appears the moment Pinnacle lists it, with no request or config change on your side.

Smaller leagues rotate in and out of the upstream offer, so a key is live only while that league has active events. GET /v1/sports is the authoritative list of what is live right now, and the umbrella basketball key aggregates every child league in a single call. Any key is queryable at /v1/sports/{sport_key}/odds, /props, /ev, /arbitrage, /consensus and the other per-sport endpoints.

Bookmaker Keys

This table is a subset. GET /v1/bookmakers is the authoritative list and the authoritative count; ?all=true adds merged and decommissioned keys with their status, so you can tell "we never had it" from "it wound down".

Market Keys

The most-used market keys per sport. Hit /v1/sports/{sport_key}/props/markets for the full live list.

MLB

player_total_bases, player_hits, player_home_runs, player_rbis, player_runs, player_singles, player_doubles, player_triples, player_walks, player_strikeouts, player_pitcher_outs, player_hits_allowed, player_earned_runs, player_hits_runs_rbis, player_first_hit, player_first_home_run

NBA / WNBA

player_points, player_rebounds, player_assists, player_threes, player_steals, player_blocks, player_turnovers, player_pra (pts+reb+ast), player_pts_rebs, player_pts_asts, player_rebs_asts, player_double_double, player_triple_double

NHL

player_goals, player_assists, player_points_nhl, player_shots_on_goal, player_saves, player_anytime_goal, player_powerplay_points, player_first_goal_scorer, player_anytime_goal_scorer

NFL

player_pass_yds, player_pass_tds, player_pass_completions, player_rush_yds, player_rec_yds, player_receptions, player_anytime_td, player_first_td, player_longest_rec, player_interceptions

Soccer

player_anytime_goalscorer, player_shots_on_target, player_assists, player_goals_assists, player_fouls, player_total_sets, plus the standard h2h, spreads, totals at the game level.

Migration from the-odds-api

If you're already using TOA, the URL surface for moneyline/spread/total odds is API-compatible. Change the host and you're done:

# Was:
TOA_BASE = "https://api.the-odds-api.com/v4"

# Now:
TOA_BASE = "https://parlay-api.com/v1"

Your existing TOA Python clients pointing at this base URL will work for /sports, /sports/{key}/odds, /sports/{key}/events, and /historical/sports/{key}/odds. Player props are available at /sports/{key}/props with a different (better) shape, see Player Props.

Detailed comparison: parlay-api.com vs the-odds-api

Embeddable Odds Widget

Need live odds on a page without writing any code? One script tag renders a compact moneyline table (next games, up to 4 major US books) into any page. Keyless and free; the visible "Live odds by ParlayAPI" footer link is the license. Odds are cached server-side for about a minute per sport.

<div data-parlayapi-widget data-sport="americanfootball_nfl"></div>
<script async src="https://parlay-api.com/widget.js"></script>

Pick a sport and preview it live at parlay-api.com/widget. The backing feed is GET /v1/widget/odds?sport={sport_key} (keyless, h2h only, 60 requests/hour per IP, honest cache_age_seconds in the response). For full data in your own UI, use GET /v1/sports/{sport_key}/odds with an API key.