{"info":{"title":"BettorOdds API","version":"1.0.0","description":"Live and historical odds from 25 sportsbooks, exchanges and DFS apps, with one key.\n\n**Start here:** the guide at https://api.bettorodds.co/docs is written so an AI assistant can follow it. Paste that link into Claude, ChatGPT, Codex or Cursor along with what you want to build.\n\nSend your key as `Authorization: Bearer ` (or `X-API-Key`). Every paid call counts as one request; a call that fails (4xx other than 429, or 5xx) is not counted. `GET /v1/usage` shows what is left this period. 429 `rate_limited` means slow down and retry after a second; 429 `quota_exhausted` means this period's requests are used up.\n\nKeep your key on a server. Calls from a web browser are refused with `browser_not_supported` and are not charged. For Lovable, Bolt or v0, put the call in a Supabase Edge Function or an API route (see the guide).\n\nHistory (Research plan) has every price change we received, about two days behind live; use the live calls for anything newer.\n\nNo code at all: add https://api.bettorodds.co/mcp as a connector in Claude, ChatGPT or Cursor."},"paths":{"/v1/odds":{"get":{"summary":"Main game lines for every event in a league","security":[{"bearer":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"description":"Slate"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"parameters":[{"in":"query","name":"league","schema":{"type":"string"},"example":"nfl","required":true,"description":"League id"},{"in":"query","name":"sportsbooks","schema":{"type":"string"},"required":false,"description":"Comma-separated sportsbook ids"},{"in":"query","name":"markets","schema":{"type":"string"},"required":false,"description":"Comma-separated market names"}]}},"/v1/usage":{"get":{"summary":"Your allowance, usage, history count and reset time (free)","security":[{"bearer":[]}],"responses":{"200":{"description":"Usage"}}}},"/v1/events":{"get":{"summary":"Upcoming and live events, by league and/or team","security":[{"bearer":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"description":"Events"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"parameters":[{"in":"query","name":"league","schema":{"type":"string"},"example":"nfl","required":false,"description":"League id. Required unless team is given."},{"in":"query","name":"team","schema":{"type":"string"},"example":"ravens","required":false,"description":"Team or player name to search for (case-insensitive, matches part of a name or the exact abbreviation)"},{"in":"query","name":"status","schema":{"type":"string"},"required":false,"description":"upcoming or live"}]}},"/v1/leagues":{"get":{"summary":"Leagues with current events (free)","responses":{"200":{"description":"Leagues"}}}},"/v1/markets":{"get":{"summary":"Market names seen for a league (free)","responses":{"200":{"description":"Markets"}},"parameters":[{"in":"query","name":"league","schema":{"type":"string"},"example":"nfl","required":true,"description":"League id from /v1/leagues"}],"description":"Names are each book's own, not normalized across books: one kind of bet can appear under several names (\"First Basket\" at some books, \"First Field Goal\" at others), and similar names can settle differently."}},"/v1/sportsbooks":{"get":{"summary":"Sportsbooks we cover and their live status per league (free)","responses":{"200":{"description":"Sportsbooks"}}}},"/v1/history/events":{"get":{"summary":"Past events in a league by start date (Pro or Research)","security":[{"bearer":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"description":"Events"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"parameters":[{"in":"query","name":"league","schema":{"type":"string"},"example":"nfl","required":true,"description":"League id"},{"in":"query","name":"from","schema":{"type":"string"},"example":"2026-10-01T00:00:00Z","required":true,"description":"ISO 8601 start"},{"in":"query","name":"to","schema":{"type":"string"},"example":"2026-10-08T00:00:00Z","required":true,"description":"ISO 8601 end (31 days max)"}]}},"/v1/events/{event_id}/odds":{"get":{"summary":"Current odds for one event, grouped by sportsbook and market","security":[{"bearer":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"event":{"$ref":"#/components/schemas/Event"},"sportsbooks":{"type":"object","additionalProperties":{"type":"object","properties":{"markets":{"$ref":"#/components/schemas/Markets"}}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"description":"Odds"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"parameters":[{"in":"path","name":"event_id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"sportsbooks","schema":{"type":"string"},"example":"draftkings,fanduel","required":false,"description":"Comma-separated sportsbook ids (default: all)"},{"in":"query","name":"markets","schema":{"type":"string"},"required":false,"description":"Comma-separated market names"},{"in":"query","name":"players","schema":{"type":"string"},"required":false,"description":"Comma-separated player names"},{"in":"query","name":"main","schema":{"type":"string"},"required":false,"description":"true for main lines only"}]}},"/v1/history/events/{event_id}/odds":{"get":{"summary":"Odds as they stood at a moment, or at close (Pro or Research)","security":[{"bearer":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"description":"Odds at a time"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"parameters":[{"in":"path","name":"event_id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"league","schema":{"type":"string"},"example":"nfl","required":true,"description":"League id"},{"in":"query","name":"at","schema":{"type":"string"},"example":"close","required":true,"description":"ISO 8601 time, or close (last odds before start)"},{"in":"query","name":"sportsbooks","schema":{"type":"string"},"example":"draftkings,ps3838","required":true,"description":"1 to 10 comma-separated sportsbook ids"},{"in":"query","name":"markets","schema":{"type":"string"},"required":false,"description":"Comma-separated market names"}]}},"/v1/history/events/{event_id}/changes":{"get":{"summary":"Every change to one market at one sportsbook (Pro or Research)","security":[{"bearer":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"description":"Changes"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"parameters":[{"in":"path","name":"event_id","schema":{"type":"string","format":"uuid"},"required":true},{"in":"query","name":"league","schema":{"type":"string"},"example":"nfl","required":true,"description":"League id"},{"in":"query","name":"sportsbook","schema":{"type":"string"},"example":"draftkings","required":true,"description":"Sportsbook id"},{"in":"query","name":"market","schema":{"type":"string"},"example":"Moneyline","required":true,"description":"Market name"},{"in":"query","name":"outcome","schema":{"type":"string"},"required":false,"description":"One outcome id"},{"in":"query","name":"cursor","schema":{"type":"string"},"required":false,"description":"next_cursor from the previous page"}]}}},"openapi":"3.0.3","servers":[{"url":"https://api.bettorodds.co"}],"components":{"schemas":{"Meta":{"type":"object","properties":{"request_id":{"type":"string"},"sportsbooks":{"type":"object","additionalProperties":{"type":"object","properties":{"lag_s":{"type":"number","nullable":true},"status":{"enum":["live","stale","unknown"],"type":"string"}}}},"generated_at":{"type":"string","format":"date-time"}}},"Team":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"abbreviation":{"type":"string","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Event":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"away":{"$ref":"#/components/schemas/Team"},"home":{"$ref":"#/components/schemas/Team"},"live":{"type":"boolean"},"name":{"type":"string","nullable":true},"league":{"type":"string"},"start_time":{"type":"string","format":"date-time","description":"Scheduled start. The game itself can begin a few minutes later (an NBA tip usually comes about 10 minutes after the listed time)."},"sportsbooks":{"type":"array","items":{"type":"string"}}}},"Markets":{"type":"array","items":{"type":"object","properties":{"market":{"type":"string","description":"The book's own market name. Names aren't normalized across books, and markets with similar names can settle differently (\"First Basket\" and \"First Field Goal\", for example), so check each book's rules before you treat two markets as the same bet."},"outcomes":{"type":"array","items":{"$ref":"#/components/schemas/Outcome"}}}}},"Outcome":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Stable BettorOdds outcome id."},"line":{"type":"number","nullable":true},"link":{"type":"string","nullable":true,"description":"Deep link to the bet at the sportsbook (current odds only)."},"main":{"type":"boolean","description":"The book's main line for this market."},"name":{"type":"string"},"side":{"type":"string","nullable":true,"description":"Over / Under, when the market has sides."},"price":{"type":"integer","nullable":true,"description":"American odds."},"locked":{"type":"boolean","description":"The book has suspended this outcome, as our source reports it. While locked, `price` is the last price before the suspension and can't be bet."},"player":{"type":"string","nullable":true},"player_id":{"type":"string","nullable":true,"description":"Stable BettorOdds player id, the same for one player across books: match players on it, not on `player`, whose spelling varies by book (accents, suffixes, nicknames). Exceptions: Splash Sports and Circa players carry their own ids, and a few Polymarket players do too."},"price_decimal":{"type":"number","nullable":true}}}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}}}}