FAQ - Common Questions and Troubleshooting

An odds API is a programmatic interface that delivers real-time and historical sports betting odds — moneylines, spreads, totals, and player props — from sportsbooks directly into your app. Unlike a sports stats API, an odds API focuses on bookmaker prices and lines. SportsGameOdds provides all of this through one REST and WebSocket API, with live scores and settlement data included.

SportsGameOdds is a REST API that delivers real-time betting odds, scores, stats, and settlement data from %numBookmakersPlus% sportsbooks across %numLeaguesPlus% leagues and %numSportsPlus% sports. Instead of scraping bookmakers yourself, you get clean, structured data through simple API calls — updated every 30–60 seconds with moneylines, spreads, totals, player props, alternate lines, and more.

We cover %numLeaguesPlus% leagues across %numSportsPlus% sports — including NFL, NBA, MLB, NHL, UFC, EPL, La Liga, Champions League, and many more — with odds from %numBookmakersPlus% bookmakers like DraftKings, FanDuel, BetMGM, Pinnacle, Bet365, and PrizePicks. We're continuously adding coverage.

Yes. SportsGameOdds aggregates odds from %numBookmakersPlus% bookmakers, including sharp books like Pinnacle alongside major sportsbooks such as DraftKings, FanDuel, BetMGM, Bet365, and Caesars. We also include DFS pick'em lines from PrizePicks and Underdog, plus prediction-market prices from Kalshi and Polymarket — all normalized into one consistent schema.

We provide pre-match and live odds across all major bet types: moneylines, spreads, over/unders, 3-way moneylines, player props, team props, alternate lines, and more — for full game, halves, quarters, and other periods. We also provide live scores, box scores, team and player stats, market settlement/outcomes, consensus odds with vig removed, and deeplinks to bookmaker bet slips.

Odds accuracy is 99.9%+ via direct bookmaker feeds, scores and stats are 99.5%+ verified against official sources, and event metadata is 99.9%+. Odds update every 30–60 seconds on average, with near-instant streaming updates available on the AllStar plan.

We charge per event, not per market or bookmaker. A single NBA game with 100 markets across 20 bookmakers costs 1 object — compared to potentially 2,000 units with per-market pricing from competitors. This makes SportsGameOdds 60–80% cheaper for most use cases, with fully predictable billing. We also offer an perpetually free tier.

Yes! Our free Amateur plan includes 10 requests per minute, 2,500 objects per month, and full access to all sports, leagues, and bookmakers. It's perfect for prototyping and evaluating the API.

Most developers are up and running within a few hours. We provide official SDKs for JavaScript, Python, Ruby, Go, and Java, plus a quickstart guide with code examples. Sign up, get your API key instantly, and make your first request in minutes.

Sign up, select a plan (free tier available), and your API key will be delivered to your email immediately.

Include your API key in one of two ways: as a header (recommended) using x-api-key: YOUR_API_KEY, or as a query parameter using ?apiKey=YOUR_API_KEY. The header method is recommended because it keeps your API key out of URL logs.

Check out our quickstart guide for step-by-step instructions with code examples in JavaScript, Python, Ruby, PHP, Java, and more. You'll be up and running in minutes.

Yes! Official SDKs are available for TypeScript/JavaScript (npm install sports-odds-api), Python (pip install sports-odds-api), Ruby (gem install sports-odds-api), Go, and Java. SDKs include auto-pagination, type safety, retry logic, and error handling.

Yes, you can download the Postman Collection JSON file from our Postman Collection page.

Not recommended, as this exposes your API key publicly. Instead, create a backend proxy that makes API calls on behalf of your frontend, or set up a server-side process that syncs data to your database and have the frontend query that instead.

Yes! We provide live odds for games currently in progress. Use the live=true parameter to filter for only live games, e.g., /events?leagueID=NBA&live=true.

Yes! We provide extensive player prop coverage across all major sports — points, assists, rebounds, passing yards, strikeouts, and many more. Props include settlement data with actual player performance values so you can determine outcomes programmatically.

Yes, we support alternate lines on both main markets and prop bets including player props. Add the includeAltLines=true parameter when making a request to the /events endpoint. In general, you're more likely to receive alt lines on larger and more popular markets and sportsbooks. Note that alt lines significantly increase response size, so only include them when needed.

Yes. We provide live scores, box scores (scores by period), team stats, and player stats for virtually all supported leagues. We also provide settlement/outcome data for odds markets — every odds item includes a score field reflecting the actual result, so you can determine bet outcomes programmatically.

Yes we do. However, we don't guarantee that every market for every bookmaker will include a deeplink. Each event includes event-level deeplinks in links.bookmakers, and individual odds include bookmaker-specific deeplinks. We're continuously adding more deeplink coverage across bookmakers.

Yes, but availability can vary. Depending on your plan, you may have access to up to 2 years of historical data. We're expanding historical data access in phases: first event metadata and final team scores, then team and player stats with main market opening/closing odds, then prop markets and bookmaker-specific odds. Use the startsAfter and startsBefore parameters to query historical events by date.

Use the /markets endpoint to get the most up-to-date list of supported markets by league and bookmaker. The endpoint defaults to isSupported=true, returning fully supported markets.

Yes, as part of our odds API, we offer some prediction markets in one unified API. For example, Kalshim Polymarket and novig.

A single request is counted as 1 each time you make a call to our API regardless of how much data was returned. An object represents the top-level items returned in a request. So for example if you make a call to the /events endpoint and it returns 10 events, that counts as 10 objects. Unlike other APIs which charge you for each odds market + bookmaker returned, SportsGameOdds lets you get as many odds and bookmakers as you want and only charges you once per game.

This depends heavily on your use case. Here are broad rules of thumb: A few hundred to a few thousand objects for local development. Tens of thousands to hundreds of thousands for small personal projects. Hundreds of thousands for production apps serving real customers. Millions for production apps that sync data frequently across many leagues. Check the /account/usage endpoint to track your current usage.

Our pricing model charges per event, not per market or bookmaker. A single NBA game with 100 markets across 20 bookmakers costs 1 object with SportsGameOdds vs. potentially 2,000 units with per-market-per-bookmaker pricing. This means 60-80% lower costs, predictable billing, and no need to optimize which data you fetch.

Rate limits vary by plan tier. The free Amateur plan includes 10 requests/min and 2,500 objects/month. Paid plans (Rookie, Pro, AllStar) offer progressively higher limits up to unlimited. Check your current usage with the /account/usage endpoint.

You'll receive a 429 Too Many Requests error. Rate limits reset at the start of each interval. To handle this: wait and retry, check which limit you hit using /account/usage, optimize requests using filters to reduce object count, or upgrade your plan if consistently hitting limits. The response includes a Retry-After header indicating when to retry.

Call the /account/usage endpoint. It returns your current request counts and object counts across all rate limit intervals (per-minute, per-hour, per-month). This endpoint doesn't count against your rate limits.

Visit our account page, enter the email you signed up with, and you'll receive a link to access your subscription portal. From there you can manage your subscription and billing information. We're also happy to make changes for you — fill out our subscription form.

The oddID uniquely identifies a specific betting option using the format: {statID}-{statEntityID}-{periodID}-{betTypeID}-{sideID}. For example, points-home-game-ml-home is the moneyline on the home team (full game), points-all-game-ou-over is the total points over (full game), and assists-LEBRON_JAMES_NBA-game-ou-over is LeBron assists over (player prop).

fairOdds are consensus odds with juice/vig removed, representing true probability. bookOdds are consensus odds across bookmakers with juice included. Use fairOdds to calculate true implied probability and compare individual bookmaker odds (in the byBookmaker object) to find value bets.

The main bet types are ml (moneyline), sp (spread), ou (over/under), ml3way (3-way moneyline for soccer), yn (yes/no), and eo (even/odd). Each bet type has associated sideIDs — for example, ml has home and away sides, ou has over and under sides.

statEntityID identifies who a stat applies to: home (home team), away (away team), all (combined/total), or a specific playerID for player props (e.g., LEBRON_JAMES_NBA).

periodID defines the time segment of a game: game (full game), reg (regulation only), 1h/2h (halves), 1q-4q (quarters), 1p-3p (hockey periods), 1i-9i (innings), 1s-5s (tennis sets), and ot (overtime). Available periods vary by sport.

The statID of "points" represents the primary scoring stat used to determine the winner — actual points in basketball/football, runs in baseball, goals in hockey/soccer, and sets in tennis. This allows consistent querying across sports (e.g., points-home-game-ml-home works for any sport). Sport-specific stats like goals or runs are also available.

Use cursor-based pagination for large result sets. The first request returns a nextCursor value. Pass that cursor to the next request: /v2/events?leagueID=NBA&limit=50&cursor={nextCursor}. Continue until nextCursor is null. Increase the limit parameter (default 10) to get more results per request. Cursors are opaque strings — don't parse or construct them.

Use specific filters for smaller responses — more parameters means faster requests. Specify oddID when you only need specific markets. Avoid includeAltLines=true unless needed as it dramatically increases response size. Use appropriate date ranges with startsAfter/startsBefore. Cache responses since pre-game odds don't change frequently.

Recommended polling intervals: 15-30 minutes for games 7+ days out, 5-15 minutes for games 24-48 hours out, 2-5 minutes on game day, 30-60 seconds for live in-game odds. For critical moments, use the streaming API (AllStar plan). Cache data longer for distant games — many markets aren't offered until 24-48 hours before gametime.

The Streaming API (AllStar plan) uses WebSockets via the Pusher protocol for instant updates. Three feeds are available: events:live (all live games), events:upcoming (upcoming by league), and events:byid (specific event updates). Get connection details from /v2/stream/events, connect via WebSocket, receive eventID notifications when data changes, then fetch updated data via /v2/events.

When you provide eventID or eventIDs, the API uses only those IDs to fetch results. All other query filters — sportID, leagueID, live, started, finalized, startsAfter, startsBefore, etc. — are ignored. This is by design for optimal query performance. Response-shaping parameters like oddID, bookmakerID, playerID, includeAltLines, and includeOpposingOdds still apply normally to the returned data.

No. Since every league belongs to exactly one sport, providing leagueID makes sportID redundant. If you pass both, sportID is ignored. Using leagueID alone results in more targeted, faster queries.

A 401 Unauthorized error means authentication failed. Common causes: missing the x-api-key header, whitespace in your API key (use trim()), wrong header name (must be exactly x-api-key in lowercase), or an old/revoked key. Make sure you're including the header correctly on every request.

A 403 Forbidden error means your key lacks permission. Causes include: cancelled subscription, failed payment, trying to access a feature not in your plan (e.g., streaming requires AllStar), or using the wrong API version. Check the error message field for specifics.

A 429 Too Many Requests error means you've exceeded rate limits. Wait for limits to reset (each minute/hour/month), check which limit you hit using /account/usage, optimize requests using filters to reduce objects returned, or upgrade your plan.

Implement retry logic with exponential backoff. For 429 errors, wait and retry after the Retry-After period. For other 4xx errors, don't retry — fix the request. For 5xx errors, retry with increasing delays.

We can add additional leagues, regional bookmakers, and exchange data through custom plans. Most additions can be completed within 1-2 weeks.

Yes. If our standard plans don't fit your needs — whether you need higher rate limits, dedicated infrastructure, custom data feeds, additional leagues or bookmakers, or SLA guarantees — we'd love to talk.

Yes, we offer discounts for annual commitments and high-volume use cases.

Yes. Our AllStar plan includes a real-time streaming API using WebSockets that notifies you instantly when odds change, events start or finish, or scores update. Contact api@sportsgameodds.com to learn more or upgrade.

Use the contact form or email api@sportsgameodds.com. For data issues, include the eventID if possible. We typically respond within one business day and resolve data issues within 1–2 weeks.

All plans include email support and access to our documentation. Paid plans receive priority response times. Enterprise customers get dedicated support with faster SLAs.