Everything developers ask about TheOddsAPI

TheOddsAPI is a real-time sports odds API built for developers, trading desks, and model builders. It aggregates odds from 50 bookmakers across 24 sports into a single normalized REST endpoint. Coverage spans NBA, NFL, MLB, NHL, NCAAB, NCAAF, WNBA, MLS, Tennis, Cricket, Boxing, MMA, and European soccer including EPL, Champions League, La Liga, Bundesliga, Serie A, Ligue 1, Eredivisie, and EFL Championship. TheOddsAPI goes beyond raw odds with an intelligence layer that includes Pinnacle-anchored edge detection, fair odds calculations, and consensus pricing. Odds refresh as frequently as every 30 seconds.

TheOddsAPI aggregates odds from up to 50 bookmakers across US, UK, European, and Australian regions. Professional tier covers US bookmakers (DraftKings, FanDuel, BetMGM, Caesars, BetRivers, Bovada, and more). Business tier adds international books including Pinnacle (the sharp anchor), Betfair Exchange, William Hill, Marathonbet, and Unibet (50+ books total). Pinnacle is treated as the sharp anchor for edge detection, while soft book lines from DraftKings and FanDuel are where most pricing inefficiencies appear. All odds are normalized into a single JSON response with American and Decimal formats.

TheOddsAPI provides player prop markets for NBA, NHL, and MLB. Available markets include points, rebounds, assists, PRA (points + rebounds + assists), pitcher strikeouts, batter hits, batter total bases, and additional stat categories. Props include Pinnacle sharp lines alongside soft book pricing, so you can identify props where the soft books are out of line with the sharp market. Available on the Business plan at $99/month.

TheOddsAPI maintains a historical odds archive covering h2h, spreads, totals, and player props across 22 sports with multi-bookmaker snapshots. Unlike most providers that charge per historical query, TheOddsAPI historical requests cost zero additional credits on the Business plan ($99/month). Data is designed for backtesting models, training algorithms, and analyzing how lines moved from open to close across all 50 bookmakers.

TheOddsAPI offers three tiers. Free: $0/month with 25 requests per day, limited to NBA and MLB, h2h markets only. Professional: $29/month with 20,000 requests, full access to 24 sports, all core markets (h2h, spreads, totals), and US sportsbooks (DraftKings, FanDuel, BetMGM, Caesars, BetRivers, and more). Business: $99/month with 200,000 requests, everything in Professional plus Pinnacle (sharp anchor) and international books (UK, EU, AU regions, 50+ books total), player props, Pinnacle-anchored edge detection, fair odds, consensus pricing, and the full historical odds archive at zero extra credit cost.

TheOddsAPI is built for arbitrage detection. It aggregates odds from 50 bookmakers into a single normalized response, enabling line comparison across books in one call. The Business plan goes further with a dedicated edge detection endpoint that pre-computes cross-book pricing inefficiencies against Pinnacle, the sharpest bookmaker globally. Edges are surfaced with the exact margin in points, so your code can act on them directly without building comparison logic from scratch.

Request a TheOddsAPI key by emailing hello@theoddsapi.com or using the signup form at theoddsapi.com. Free tier keys are issued within minutes and include 25 requests per day covering NBA and MLB h2h markets. No credit card is required. Upgrading to Professional or Business unlocks full sport and market coverage with the same API key, no migration or code changes needed.

TheOddsAPI returns JSON via a standard REST interface. Odds values are available in American (+150, -110) or Decimal (2.50, 1.91) notation, controlled by the oddsFormat query parameter. Each response includes the bookmaker name, last update timestamp, and market-specific outcomes. All endpoints follow RESTful conventions with standard HTTP status codes. No SDK or proprietary client library required.

TheOddsAPI refreshes odds as frequently as every 30 seconds on the Business plan and every 60 seconds on Professional. Each odds object includes a last_update timestamp in ISO 8601 format so you can verify freshness programmatically. The API uses ETag-based caching: if odds haven't changed since your last request, the response returns a 304 with zero credit cost. This means you can poll aggressively without burning through your quota.

TheOddsAPI is a standard REST API that works with any language capable of making HTTP requests. Common integrations include Python (requests, aiohttp), JavaScript/Node.js (fetch, axios), Go, Java, Ruby, and C#. Authentication is a single apiKey query parameter appended to the request URL. No SDK installation, no API client generation, no dependency management.

TheOddsAPI uses a single x-api-key HTTP header on every request. Example: curl -H 'x-api-key: YOUR_KEY' 'https://api.theoddsapi.com/odds/?sport_key=basketball_nba&regions=us&markets=h2h'. No OAuth, no bearer tokens, no request signing. One header, one key. Keys are issued per account and work across all endpoints your plan supports.

TheOddsAPI covers English Premier League, Champions League, Europa League, La Liga, Bundesliga, Serie A, Ligue 1, Eredivisie, EFL Championship, Liga MX, and MLS. Each league is a separate sport key (e.g., soccer_epl, soccer_spain_la_liga). All leagues include h2h, spreads, and totals markets from up to 50 bookmakers. Historical archive access and edge detection are available for all soccer leagues on the Business plan.

TheOddsAPI provides UFC and MMA odds with h2h (moneyline) markets from major bookmakers including DraftKings, FanDuel, BetMGM, and Pinnacle. MMA events are available under the sport key mma_mixed_martial_arts on all paid plans. MMA is a live-odds sport with no historical archive. Edge detection still applies: the API flags moneyline discrepancies across books against the Pinnacle sharp line.

TheOddsAPI covers NFL regular season, playoffs, and Super Bowl with h2h (moneyline), spreads, and totals markets from 50 bookmakers. NFL data is available under americanfootball_nfl with NCAAF as a separate sport key. Both are seasonal. Full historical archives let you backtest NFL models against actual multi-bookmaker lines from prior weeks, available on the Business plan.

TheOddsAPI serves odds for both live and upcoming events. When a game is in progress, the API returns current bookmaker lines updated as frequently as every 30 seconds. The commenced_time field indicates whether a game has started, and each bookmaker entry carries its own last_update timestamp. This lets you track how lines shift during a game and react to in-play movement across all 50 books simultaneously.

TheOddsAPI supports four market types: h2h (moneyline), spreads (handicap), totals (over/under), and player props. H2h, spreads, and totals cover all 24 sports. Player props cover NBA, NHL, and MLB on the Business plan. Markets can be combined in a single request. The intelligence layer adds fair odds (vig-removed true probability) and edge detection (sharp vs. soft book discrepancies) on top of raw market data.

TheOddsAPI is the standard data source for sports betting bots. It provides normalized odds from 50 bookmakers via a single REST call, eliminating the need to scrape individual sportsbook sites. A typical bot polls at 30-60 second intervals and compares lines across books. On the Business plan, the edge detection endpoint pre-computes which books are mispriced against Pinnacle's sharp line, so your bot can skip the comparison logic and act on edges directly. Start with the free tier (25 requests/day) for prototyping.

TheOddsAPI provides historical odds archives specifically designed for backtesting. The historical endpoint returns multi-bookmaker snapshots for h2h, spreads, and totals across 22 sports, letting you test strategies against actual market prices at specific points in time. You can backtest across sharp (Pinnacle) and soft (DraftKings, FanDuel) lines simultaneously to measure how your model performs against different market conditions. Historical requests cost zero credits on the Business plan ($99/month).

An arbitrage bot built on TheOddsAPI polls for a given sport, scans all 50 bookmakers in the response, and flags events where the combined implied probability across outcomes drops below 100%. Because all bookmaker data comes back in a single normalized call, your bot needs one request per sport to scan every book. The Business plan adds a shortcut: the edge detection endpoint surfaces which specific books are out of line with Pinnacle, so you can prioritize the highest-margin opportunities without computing them yourself.

Sports traders on Polymarket use TheOddsAPI to price prediction market positions against regulated sportsbook odds. The key advantage is access to 50 bookmakers including Pinnacle in a single call, giving you the sharpest available implied probability for any event. When a Polymarket contract trades at 62 cents but the sharp sportsbook implied probability is 58%, that spread is your edge. TheOddsAPI's 30-second refresh rate on the Business plan means you can track line movement in near real-time and catch contracts before the prediction market reprices.

TheOddsAPI returns odds from up to 50 bookmakers in a single JSON response per sport. Each bookmaker entry includes the book name, region, last update timestamp, and market outcomes. Request your target sport with the regions you want (us, uk, eu, au), then iterate the bookmakers array to find the best line. Beyond raw comparison, the fair odds endpoint strips the vig to show you the true implied probability, so you know whether the best line is actually offering positive expected value or just the least bad price.

TheOddsAPI is commonly used to power Discord bots. The REST API returns JSON that maps cleanly into Discord embed formatting. A typical setup uses Node.js or Python to poll on a schedule, then posts formatted odds comparisons or edge alerts to a channel via webhook. The edge detection endpoint is particularly useful here: instead of posting raw odds tables, your bot can post actionable alerts like "FanDuel NBA Lakers +4.5 is 2.3 points off Pinnacle sharp line." Free tier (25 requests/day) supports hobby bots, Professional handles active communities.

TheOddsAPI offers a free tier with 25 API requests per day, no credit card required. Free access covers NBA and MLB with h2h (moneyline) markets. It is designed for evaluating the API, building prototypes, and testing integrations before committing to a paid plan. Upgrading to Professional ($29/month) unlocks all 24 sports, all core markets, and 20,000 requests per month using the same API key. No code changes required to upgrade.

TheOddsAPI does not enforce a hard rate limit per second. Usage is metered by monthly request count: Free allows 25 requests/day, Professional allows 20,000/month, and Business allows 200,000/month. Requests that return a 304 (not modified) via ETag caching consume zero credits. Your remaining balance is returned in the x-requests-remaining response header after every call, so your code can throttle automatically.

TheOddsAPI uses a polling model via standard REST endpoints. No WebSocket or webhook push delivery. The recommended polling interval is 30-60 seconds depending on plan tier. ETag-based caching ensures you only consume credits when data has actually changed. This model keeps integration simple, works with any HTTP client, and avoids the complexity of maintaining persistent connections or webhook infrastructure.

TheOddsAPI supports filtering by both region and individual bookmaker. The regions parameter filters by geography: us, uk, eu, au (comma-separated for multiple). The bookmakers parameter filters to specific books by key (e.g., bookmakers=draftkings,fanduel,pinnacle). Filtering reduces response size and credit consumption by returning only the data you need. This is useful when your strategy only cares about specific sharp or soft books.

TheOddsAPI Professional ($29/month) gives you 20,000 requests, 24 sports, h2h/spreads/totals, and US sportsbooks (DraftKings, FanDuel, BetMGM, Caesars, BetRivers, and more). Business ($99/month) gives you 200,000 requests and unlocks the features that serious operators need: player props for NBA/NHL/MLB, Pinnacle-anchored edge detection, fair odds (vig-removed true probability), consensus pricing, and the full historical archive across 22 sports at zero extra credit cost. Both use the same API key. Upgrading unlocks endpoints, no code migration.

Pinnacle is the sharpest bookmaker globally because they accept high-volume professional bettors, which forces their lines to be maximally efficient. TheOddsAPI uses Pinnacle as the baseline and compares every other bookmaker against it. When DraftKings, FanDuel, or another soft book offers a line that deviates from Pinnacle by a meaningful margin, the edge detection endpoint flags it with the exact differential in points. This is the same sharp-vs-soft framework professional syndicates use, delivered as an API endpoint.

TheOddsAPI calculates fair odds by removing the bookmaker margin (vig/juice) from the sharpest available lines. The fair odds endpoint returns the estimated true probability for each outcome as a decimal value with the overround stripped. You can compare any bookmaker's price against this baseline to instantly see whether you're getting positive or negative expected value, without building your own devigging model.

Positive expected value (+EV) bets occur when a bookmaker's odds imply a lower probability than the true probability of the outcome. TheOddsAPI identifies +EV opportunities through two endpoints: fair odds (strips vig from sharp lines to estimate true probability) and edge detection (compares every bookmaker against Pinnacle's efficient line). If a soft book's price exceeds the fair odds value, the bet is +EV. Both endpoints are available on the Business plan and update with each odds refresh cycle.

TheOddsAPI is used by Polymarket sports traders to benchmark prediction market contracts against real sportsbook pricing. The workflow: pull real-time odds from 50 bookmakers, convert to implied probability, and compare against the Polymarket contract price. What makes this effective is the fair odds endpoint, which strips the vig and gives you a clean true-probability estimate. If a Polymarket contract for "Lakers win" is priced at $0.55 but TheOddsAPI fair odds show 51.2% true probability, the contract is overpriced. The 30-second refresh rate on Business lets you track line movement and react before the prediction market adjusts.

Kalshi event contracts for sports outcomes work like binary options. TheOddsAPI gives traders the sportsbook-derived pricing benchmark for those contracts. The edge detection endpoint is particularly useful here: it already computes which bookmakers are mispriced relative to Pinnacle's sharp line, and that same framework applies to Kalshi contracts. If Pinnacle implies 47% on an outcome and Kalshi is selling the "yes" contract at $0.52, the contract is 5 points rich. TheOddsAPI covers 24 sports with h2h, spreads, and totals, matching the most common Kalshi contract types.

Prediction market arbitrage exploits price differences between platforms like Polymarket or Kalshi and regulated sportsbooks. TheOddsAPI provides the sportsbook side of that equation: real-time odds from 50 bookmakers across 24 sports, refreshed every 30 seconds on Business. The execution flow: convert sportsbook odds to implied probability using the fair odds endpoint, compare against the prediction market contract price, and act when the spread exceeds your transaction costs. The single-call multi-book response means you can scan the entire sportsbook market for one event in one request, making cross-platform arbitrage scans practical at production speed.

A 401 Unauthorized from TheOddsAPI means your API key is missing, invalid, or expired. The most common mistake is using the wrong header name (Authorization, Bearer, or auth) instead of x-api-key. TheOddsAPI uses x-api-key as the HTTP header name on every request. Other causes: omitting the header entirely, copy-pasting with extra whitespace, using a revoked key, or exceeding your plan quota. Test with: curl -H 'x-api-key: YOUR_KEY' https://api.theoddsapi.com/sports/. If that returns a 200 with a list of sports, your key is valid and the issue is in how your code constructs the request.

TheOddsAPI returns ETag headers. Cache the ETag, send it back as If-None-Match, and you get a 304 with zero credit cost when nothing changed. Application-side, match your TTL to the refresh cycle: 30 seconds for NBA, MLB, NFL, NHL; 60 to 300 seconds for everything else. Anything longer and you're serving stale lines pre-game.

Read X-RateLimit-Remaining and X-RateLimit-Limit on every response. Below 10 percent of monthly quota, throttle background polling (dashboards, scans) but keep critical paths (live scanning, customer requests) at full rate. ETag-cached 304s consume zero credits, so good caching makes rate limits a non-issue for most setups. On 429, exponential backoff starting at 1 second; respect Retry-After if present.

Retry on 502, 503, 504, and connection timeouts. Don't retry on 400, 401, 403, 404; those mean you have a bug, not us. Exponential backoff 1s, 2s, 4s, 8s, capped at 30s, max 5 attempts. On 429, respect Retry-After. 4xx responses ship a JSON body with a detail field that tells you what to fix.

TheOddsAPI median is 119 milliseconds, p95 is 537 milliseconds, p99 is 1.6 seconds, measured over 4,200+ recent prod requests. Cached endpoints (odds, edges, intelligence) are pre-computed during the refresh cycle and read straight from cache. Historical archive queries hit Postgres and run 500 to 1,500 milliseconds depending on date range and pagination. The API uses polling, not webhooks, so for low-latency use cases poll on the refresh cadence.

Raw market odds bake in the bookmaker's vig. Implied probabilities across all outcomes sum to more than 100 percent; the excess is their margin. Vig-removed (devigged) odds normalize that to exactly 100 percent, the book's true probability assessment with no margin baked in. /intelligence/fair-odds/ on Business tier returns devigged odds calculated from a vig-removed consensus across 30 to 50 books including Pinnacle as a sharp anchor. Use it as the input to your own +EV calc against any retail book's offered price.

CLV is the implied-probability difference between the price you took and the closing-line price (typically Pinnacle's last pre-game number). To calculate it today: capture Pinnacle on /odds/ at bet time, capture again near commence_time, devig pairwise, take the delta. Positive CLV across hundreds of bets converges 10 times faster than realized P&L for validating edge. Native CLV tooling with closing-line snapshots ships in the Quant tier coming in our July release, pre-built so you skip the scaffolding.

Pull single-leg prices from /odds/, /props/, or /best-lines/, convert each to decimal, multiply. The product is the parlay's true odds; compare to your sportsbook's offered parlay price to find mispricings. Caveat: same-game parlays are correlated. Outcomes aren't independent, so the multiplication overstates true odds, and books model that correlation in their SGP pricing. Modeling it yourself needs historical settlement data, available via /historical/settlements/ on Business tier.

edge_score = abs(line_gap) × 200 + abs(price_gap). line_gap is the spread or total difference between Pinnacle and the soft book; price_gap is the cent-value difference in their American odds. Line gaps weight more because they're more reliable signal. Recommended threshold: edge_score ≥ 50 for actionable edges. The 80 to 99 band has shown the strongest realized ROI in our internal grading data. Available on /edges/ with Business tier.

After a game completes, /historical/settlements/ joins your edge snapshots against final scores from our /scores ingestion. h2h grades on the winning team; spreads and totals grade against the actual margin. Each settlement row has a result field (hit, miss, push, void) and a payout field (return per dollar at the soft book's price). Currently 1,700+ graded standard edges across 12 sports. Player prop grading is on the roadmap; we're integrating a player game-stats vendor, and until that lands prop snapshots collect but don't grade. Settlements are available on Business tier today; advanced settlement analytics (per-band ROI, performance attribution) ship in the Quant tier coming in our July release.

The free tier is your sandbox. Same production endpoints, NBA + MLB h2h only, 25 requests per day. Build your integration against real production responses, then upgrade to Pro or Business with the same key. No separate sandbox URL, no migration, no code changes. Free keys are issued instantly, no credit card required.

American by default. Pass oddsFormat=decimal as a query param to get decimal (1.91, 2.50). Fractional isn't returned natively but converts trivially from decimal: subtract 1, express as a fraction. American for US-facing apps, decimal for European or quant work.

All timestamps are UTC, ISO 8601 with the Z suffix (e.g., 2026-05-06T19:30:00Z). commence_time, last_update, captured_at, snapshot_time, all UTC. Convert to local in your application layer. Historical archive query params (from, to) expect ISO 8601 UTC inputs.

Pinnacle runs the lowest margins in the industry and accepts large action without limiting accounts, so their lines reflect the most informed pricing available. Sharp bettors and syndicates move Pinnacle's line through size; retail books (DraftKings, FanDuel, BetMGM) lean on Pinnacle and adjust for their own positions and margins. Comparing any retail book to Pinnacle gives the highest-signal cross-book edge. /edges/ and /intelligence/ use Pinnacle as the anchor.

TheOddsAPI uses polling, not webhooks. For real-time alerts, poll the relevant endpoint at the refresh cadence (30 seconds for major sports), compare against your last-seen state, and fire your alert from your own code when a threshold trips (line moved more than X points, edge_score crossed Y). ETag caching keeps polling cheap; 304s cost zero credits. Same effective latency as webhooks for most use cases, simpler infra: no receiver, no retry queues, no replay logic. Push delivery with subscription endpoints is reserved for the Quant tier coming in our July release.

TheOddsAPI captures closing-line snapshots (the last observed price per event, book, market, and outcome before commence_time) every 5 minutes via internal materialization. Public exposure ships in the Quant tier coming in our July release, with CLV calculation, line-movement signals, and vig-removed close-vs-open analysis pre-built. Today, Pro and Business can derive an approximate close from /historical/odds/ by querying the rows nearest commence_time per book per market.