NBA API documentation
24 basketball data endpoints over REST and MCP. One key, credits per call.
Coming from stats.nba.com or nba_api? See how they compare.
Your first call
Sign up for a free key (500 credits every month, no card), swap it in for YOUR_API_KEY, and send this. get_standings costs 2 credits.
Request
curl -X POST https://mcp.dunkapi.com/v1/get_standings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"season": 2026
}'Response
{
"season": 2026,
"standings": [
{
"team_id": "25",
"abbrev": "OKC",
"display_name": "Oklahoma City Thunder",
"conference": "Western",
"wins": 64,
"losses": 18,
"conf_wins": 41,
"conf_losses": 11,
"home_wins": 34,
"home_losses": 8,
...First 14 lines. Full response and every field
REST / cURL
POST to /v1/{tool_name} with your params as JSON body. No MCP client needed:
curl -X POST https://mcp.dunkapi.com/v1/list_teams \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY"With parameters:
curl -X POST https://mcp.dunkapi.com/v1/get_standings \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"season":2026}'Save the raw JSON
Keep your key in an environment variable so it never sits in a script or a chat, and write each response to a file:
export DUNKAPI_API_KEY="your key here"
curl -s -X POST https://mcp.dunkapi.com/v1/get_standings \
-H "Content-Type: application/json" \
-H "x-api-key: $DUNKAPI_API_KEY" \
-d '{"season":2026}' \
-o get_standings.jsonThe file holds exactly what the API returned. Tools that page their results return a next_offset; send it back as offset for the next page.
ChatGPT and Claude
Both connect to the MCP server with a sign-in instead of a key: you sign in to DunkAPI once and press Allow. Step-by-step for ChatGPT and Claude.
Python
The official client is on PyPI. It has no required dependencies. Set DUNKAPI_API_KEY to your key and it is picked up automatically:
pip install dunkapiThen call any endpoint as a method (the example uses pandas, pip install "dunkapi[pandas]"):
from dunkapi import Client, to_dataframe
client = Client()
props = client.get_player_props(
game_id="401810726",
market="player_points",
bookmaker="draftkings",
)
df = to_dataframe(props, key="props")
print(df[["player_name", "line", "over_odds", "under_odds"]].head(10))Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"dunkapi": {
"url": "https://mcp.dunkapi.com/mcp?key=YOUR_API_KEY"
}
}
}Claude Code
One command:
claude mcp add dunkapi https://mcp.dunkapi.com/mcp?key=YOUR_API_KEY --transport streamable-httpFind the right call
All 24 questionsWhat timestamps mean, whether lines are pre-game, and what you can do with the data: data timing and rights.
Guides
All guidesWorking Python, JavaScript and cURL for common questions, each run against the live API.
- How do I get NBA play-by-play data in Python?get_plays
- How do I build an NBA shot chart by zone in Python?get_shot_chart
- How do I backtest NBA closing lines in Python?get_odds
- How do I compare NBA team pace and efficiency in pandas?get_team_stats
- How do I get an NBA player's game log and a rolling average?get_player_games
- How do I compare NBA player prop lines across sportsbooks?get_player_props
- How do I get NBA line movement before tip-off in Python?get_line_movement
- How do I get today's NBA schedule and scores in Python?list_games
- How do I get NBA standings in Python?get_standings
- How do I get the NBA injury report in Python?get_injuries
- How often does an NBA player go over his points line?get_prop_history
- How often does an NBA shooter go over his threes line?get_prop_history
- How often does an NBA big man go over his rebounds line?get_prop_history
- How often does an NBA playmaker go over his assists line?get_prop_history
- How often does an NBA star go over his points + rebounds + assists line?get_prop_history
- How often does a college basketball player go over his points line?get_prop_history
- How often does a college basketball player go over his rebounds line?get_prop_history
- How often does an NBA big man go over his blocks line?get_prop_history
- How often does an NBA guard go over his steals line?get_prop_history
- How do I get first quarter NBA odds history in Python?get_market_odds
Endpoints
24 endpoints by category. Each page has parameters, requests in three formats, a full example response and every response field.
Static reference1 credit/call
Basic lookup2 credits/call
- list_games2 creditsGames with scores by season, date, range or team
- get_schedule2 creditsUpcoming games with the median line across sportsbooks
- get_standings2 creditsStandings from every final game: overall, conference, home, away, last 10
- get_injuries2 creditsThe latest injury report: status, injury and expected return (NBA, WNBA)
- get_ratings2 creditsOur team Elo ratings, ranked
Stats + aggregation5 credits/call
- get_game5 creditsOne game: both box scores, every player's line, each book's line, win probability
- get_player5 creditsProfile, per-season averages and shooting splits, last 10 games
- get_player_games5 creditsA player's full game log
- get_leaders5 creditsSeason leaders per game, by percentage or in total
- get_team_stats5 creditsPace, offensive, defensive and net rating, and the four factors
- get_odds5 creditsEvery sportsbook's moneyline, spread and total for a game (5) or a day (10), with results against the line
- get_game_probabilities5 creditsWhat the market thinks of a game: average implied and fair probability for the moneyline, spreads and totals
Multi-table10 credits/call
- get_plays10 creditsPlay-by-play with shot locations, zones, expected points and win probability
- get_shot_chart10 creditsShot profile by zone for a player, team or defence, with every shot's x/y
- get_player_props10 creditsPlayer prop lines by sportsbook: the closing line (one pre-game capture per line before October 2026)
- get_prop_history10 creditsA player's prop lines against the result, game by game
- get_prop_probabilities10 creditsWhat the market thinks of a game's player props: average implied and fair probability for each player and line
- get_alt_lines10 creditsAlternate spreads and totals by sportsbook: every point on each book's ladder, opening and closing, NBA, WNBA and men's college from 2023-24
Time-series10 credits/call
- get_line_movement10 creditsSnapshots of each sportsbook's line before tip-off
- get_prop_movement10 creditsHow one player's prop line moved before a game, every capture by sportsbook
- get_market_odds10 creditsOpening and closing lines by sportsbook for the half and quarter markets (from May 2023, each game added the morning after it is played)
Reference
Authentication
Every request requires an API key. Pass it via header or query parameter:
x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY
# or (MCP only)
?key=YOUR_API_KEYVerify your email, then create an API key from the dashboard. Free accounts get 500 credits every month.
Base URL
https://mcp.dunkapi.comREST API: POST /v1/{tool} with JSON body. Works with cURL, Python, any HTTP client.
MCP: POST /mcp via Streamable HTTP. Works with Claude Desktop, Claude Code, Cursor, and any MCP client.
Rate limits
| Credit balance | Rate limit |
|---|---|
| 100 credits or more | 60 req/min |
| Under 100 credits | 10 req/min |
The limit is the same on every plan. It is burst protection, not the spend boundary; credits are that, and they are enforced per request. Running low slows you down so you notice before the balance reaches zero.
Error handling
| Code | Meaning | What to do |
|---|---|---|
| 400 | Invalid parameters | Check required fields and value types |
| 401 | Invalid or missing API key | Check your x-api-key header |
| 402 | Insufficient credits | Top up your wallet or upgrade your plan |
| 429 | Rate limit exceeded | Wait and retry (see limits above) |
| 500 | Server error | Retry with idempotency key. Credits auto-refund on server errors. |
Pass x-idempotency-key or x-request-id headers to make retries duplicate-safe.
Data coverage
Women's National Basketball Association (WNBA)
DunkAPI also serves the WNBA. Pass "league": "wnba" to any tool that lists it, or connect to https://mcp.dunkapi.com/mcp/wnba. WNBA API coverage.
NCAA Division I men's basketball (NCAAM)
DunkAPI also serves the NCAAM. Pass "league": "ncaam" to any tool that lists it, or connect to https://mcp.dunkapi.com/mcp/ncaam. NCAAM API coverage.
NCAA Division I women's basketball (NCAAW)
DunkAPI also serves the NCAAW. Pass "league": "ncaaw" to any tool that lists it, or connect to https://mcp.dunkapi.com/mcp/ncaaw. NCAAW API coverage.
National Basketball League (Australia and New Zealand) (NBL)
DunkAPI also serves the NBL. Pass "league": "nbl" to any tool that lists it, or connect to https://mcp.dunkapi.com/mcp/nbl. NBL API coverage.
| Data | Status | Coverage | Volume |
|---|---|---|---|
Games and box scores Scores, both teams' box scores and every player's line: minutes, points, shooting, rebounds, assists, steals, blocks, turnovers, fouls, plus-minus. About one game in eight from 2012-13 to 2017-18 has no box score in the source; those lines are counted from the play-by-play (97-100% exact where checked), without minutes or plus-minus. 26 games have a box score but no play-by-play. | Partial | 2003-04 to current | Every game, every player |
Play-by-play Every play with clock, score, players involved, shot type and points. | Available | 2003-04 to current | About 450 plays per NBA game |
Shot locations Each shot's x/y in feet, distance, zone and our expected points. | Available | 2003-04 to current | Every field goal attempt |
Win probability The home team's win probability after each play, as computed upstream, not by us. From 2017-18 only. | Partial | 2018 to current | After every play |
Odds Moneyline, spread and total by sportsbook; opening and closing lines from July 2020 (sportsbook odds archive), the final pregame line only in the earlier seasons. No lines before 2012-13; opening and closing lines from July 2020; player props are separate (get_player_props, from May 2023). | Partial | 2013-14 to current | 4 to 12 books per regular-season game to 2023-24; 6 to 8 with opening and closing lines since July 2020 |
Ratings Our Elo, before and after every game. | Available | 2003-04 to current | Every team, every game |
Injury report Each listed player's status, injury and expected return, captured daily (NBA and WNBA). Daily captures from launch; no history before that. | Partial | From launch | Daily |
Coverage describes the datasets DunkAPI supports. Freshness and operational health are tracked separately.
Odds snapshot definitions
opening: The first line a sportsbook posted for the game, held from 2023-24 and, from July 2020, in the sportsbook odds archive.
closing: The sportsbook's last line before tip-off.
Odds coverage currently documents the books reported with each game: 4 to 12 per regular-season NBA game from 2013-14 to 2023-24, 10 to 12 from 2020-21 (DraftKings, Caesars, BetMGM, Unibet and Betfair among them in 2023-24), plus up to eight books with opening and closing lines since July 2020, among them DraftKings, FanDuel, BetMGM, ESPN BET and Pinnacle. No lines before 2012-13, and the daily feed is one or two books a game since 2024-25; the other books come from the sportsbook odds archive. Before 2023-24 we hold each sportsbook's final pregame line, stored as the close, for 4 to 12 books per regular-season NBA game from 2013-14 (10 to 12 from 2020-21). Opening and closing lines in that daily feed start in 2023-24, usually from one book from 2024-25. Since July 2020 the sportsbook odds archive adds opening and closing lines per book for nearly every game, a median of 7 books in 2020-21 to 2022-23 and 8 since 2023-24. Daily snapshots before each game from launch.
Response format
REST API
All successful REST responses wrap the result in a data key:
{ "data": { "teams": [...], "count": 32 } }Error responses return:
{ "error": "Insufficient credits", "message": "This tool costs 5 credits, you have 2" }MCP Protocol
MCP responses follow the standard MCP tool result format. The data is returned directly (no data wrapper). Both access methods return identical data, just different envelopes.
Conventions
Seasons: the year the season ends (2025 = 2024-25); WNBA: the calendar year. Example: 2025.
Game IDs: a game id, e.g. 401705127 (a game id; find them with list_games). Get them from list_games or get_schedule.
Team abbreviations: Standard codes (BOS, LAL, NY (or a team id); list_teams has them). Use list_teams if unsure.
Pagination: Endpoints use a limit parameter. No cursor or offset. Narrow your filters to get different slices of data.
Credits: Deducted before the request executes. Automatically refunded on server errors. Monthly credits are used first, then wallet balance.