NBA API

Welcome to the BALLDONTLIE NBA API, the best NBA API on the planet. The API contains data from 1946-current. An API key is required. You can obtain an API key by creating a free account on our website. Read the authentication section to learn how to use the API key.

Download language specific libraries:

Take a look at our other APIs:

Join us on discord.

AI-Powered Integration

Using the OpenAPI Specification with AI

Our complete OpenAPI specification allows AI assistants to automatically understand and interact with our API. Simply share the spec URL with your AI assistant and describe what you want to build—the AI will handle the technical implementation.

Getting Started with AI:

Copy this URL: https://www.balldontlie.io/openapi.yml
Share it with your preferred AI assistant (ChatGPT, Claude, Gemini, etc.)
Tell the AI what you want to build (e.g., "Create a dashboard showing today's NBA games")
The AI will read the OpenAPI spec and write the code for you

Example prompts to try:

"Using the OpenAPI spec at https://www.balldontlie.io/openapi.yml, show me how to get LeBron James' season stats"
"Read the BALLDONTLIE OpenAPI spec and create a Python script that fetches today's NBA games"
"Help me understand the available NBA endpoints from this OpenAPI spec: https://www.balldontlie.io/openapi.yml"

This makes it incredibly easy for non-technical users, analysts, and researchers to leverage our sports data without needing to learn programming from scratch.

MCP Server Integration

Connect to our sports data through any MCP-compatible client using our hosted MCP server. The MCP (Model Context Protocol) server allows AI assistants to interact with our API through natural language.

Quick Setup

Add this configuration to your MCP client (e.g., Claude Desktop, or any other MCP-compatible client):

{
  "mcpServers": {
    "balldontlie-api": {
      "url": "https://mcp.balldontlie.io/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "YOUR_BALLDONTLIE_API_KEY"
      }
    }
  }
}

Open Source Implementation

Check out our open-source MCP server implementation on GitHub: https://github.com/balldontlie-api/mcp

Usage Examples

Once configured, you can ask your AI assistant natural language questions like:

"Get the current NBA standings"
"Show me LeBron James' season stats"
"What are today's NBA games?"

The MCP server provides access to all available API endpoints through conversational AI, making it easy to integrate sports data into any AI-powered application.

Account Tiers

There are three different account tiers which provide you access to different types of data. Visit our website to create an account for free.

Paid tiers do not apply across sports. The tier you purchase for NBA will not automatically be applied to other sports. You can purchase the ALL-ACCESS ($159.99/mo) tier to get access to every endpoint for every sport.

Read the table below to see the breakdown.

Endpoint	Free	ALL-STAR	GOAT
Teams	Yes	Yes	Yes
Players	Yes	Yes	Yes
Games	Yes	Yes	Yes
Game Player Stats	No	Yes	Yes
Active Players	No	Yes	Yes
Player Injuries	No	Yes	Yes
Season Averages	No	No	Yes
Game Advanced Stats	No	No	Yes
Box Scores	No	No	Yes
Team Standings	No	No	Yes
Leaders	No	No	Yes
Betting Odds	No	No	Yes
Player Props	No	No	Yes
Team Contracts	No	No	Yes
Player Contracts	No	No	Yes
Player Contract Aggregates	No	No	Yes

The feature breakdown per tier is shown in the table below.

Tier	Requests / Min	$USD / mo.
GOAT	600	39.99
ALL-STAR	60	9.99
Free	5	0

Authentication

curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")

BALLDONTLIE uses API keys to allow access to the API. You can obtain an API key by creating a free account at our website

We expect the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: YOUR_API_KEY

You must replace YOUR_API_KEY with your personal API key.

Pagination

This API uses cursor based pagination rather than limit/offset. Endpoints that support pagination will send back responses with a meta key that looks like what is displayed on the right.

{
  "meta": {
    "next_cursor": 90,
    "per_page": 25
  }
}

You can use per_page to specify the maximum number of results. It defaults to 25 and doesn't allow values larger than 100.

You can use next_cursor to get the next page of results. Specify it in the request parameters like this: ?cursor=NEXT_CURSOR.

Errors

The API uses the following error codes:

Error Code	Meaning
401	Unauthorized - You either need an API key or your account tier does not have access to the endpoint.
400	Bad Request -- The request is invalid. The request parameters are probably incorrect.
404	Not Found -- The specified resource could not be found.
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests -- You're rate limited.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Teams

Get All Teams

curl "https://api.balldontlie.io/v1/teams" \
  -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const teams = await api.nba.getTeams();

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
teams = api.nba.teams.list()

{
  "data": [
    {
      "id":1,
      "conference":"East",
      "division":"Southeast",
      "city":"Atlanta",
      "name":"Hawks",
      "full_name":"Atlanta Hawks",
      "abbreviation":"ATL"
    },
    ...
  ]
}

This endpoint retrieves all teams.

HTTP Request

GET https://api.balldontlie.io/v1/teams

Query Parameters

Parameter	Required	Description
division	false	Returns teams that belong to this division
conference	false	Returns teams that belong to this conference

Get a Specific Team

curl "https://api.balldontlie.io/v1/teams/<ID>" \
  -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const teams = await api.nba.getTeam(1);

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
teams = api.nba.teams.get(1)

{
  "data": [
    {
      "id": 1,
      "conference": "East",
      "division": "Southeast",
      "city": "Atlanta",
      "name": "Hawks",
      "full_name": "Atlanta Hawks",
      "abbreviation": "ATL"
    }
  ]
}

This endpoint retrieves a specific team.

HTTP Request

GET https://api.balldontlie.io/v1/teams/<ID>

URL Parameters

Parameter	Required	Description
ID	true	The ID of the team to retrieve

Players

Get All Players

curl "https://api.balldontlie.io/v1/players" \
  -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const players = await api.nba.getPlayers();

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
players = api.nba.players.list(per_page=25)

{
  "data": [
    {
        "id": 19,
        "first_name": "Stephen",
        "last_name": "Curry",
        "position": "G",
        "height": "6-2",
        "weight": "185",
        "jersey_number": "30",
        "college": "Davidson",
        "country": "USA",
        "draft_year": 2009,
        "draft_round": 1,
        "draft_number": 7,
        "team": {
            "id": 10,
            "conference": "West",
            "division": "Pacific",
            "city": "Golden State",
            "name": "Warriors",
            "full_name": "Golden State Warriors",
            "abbreviation": "GSW"
        }
    },
    ...
  ],
  "meta": {
    "next_cursor": 25,
    "per_page": 25
  }
}

This endpoint retrieves all players.

HTTP Request

GET https://api.balldontlie.io/v1/players

Query Parameters

Parameter	Required	Description
cursor	false	The cursor, used for pagination
per_page	false	The number of results per page. Default to 25. Max is 100
search	false	Returns players whose first or last name matches this value. For example, `?search=davis` will return players that have 'davis' in their first or last name.
first_name	false	Returns players whose first name matches this value. For example, `?search=anthony` will return players that have 'anthony' in their first name.
last_name	false	Returns players whose last name matches this value. For example, `?search=davis` will return players that have 'davis' in their last name.
team_ids	false	Returns players that belong to these team ids. This should be an array: `?team_ids[]=1&team_ids[]=2`
player_ids	false	Returns players that match these ids. This should be an array: `?player_ids[]=1&player_ids[]=2`

Get a Specific Player

curl "https://api.balldontlie.io/v1/players/<ID>" \
  -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const player = await api.nba.getPlayer(19);

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
player = api.nba.players.get(19)

{
  "data": {
    "id": 19,
    "first_name": "Stephen",
    "last_name": "Curry",
    "position": "G",
    "height": "6-2",
    "weight": "185",
    "jersey_number": "30",
    "college": "Davidson",
    "country": "USA",
    "draft_year": 2009,
    "draft_round": 1,
    "draft_number": 7,
    "team": {
      "id": 10,
      "conference": "West",
      "division": "Pacific",
      "city": "Golden State",
      "name": "Warriors",
      "full_name": "Golden State Warriors",
      "abbreviation": "GSW"
    }
  }
}

This endpoint retrieves a specific player.

HTTP Request

GET https://api.balldontlie.io/v1/players/<ID>

URL Parameters

Parameter	Required	Description
ID	true	The ID of the player to retrieve

Games

Attributes

These response attributes are worth noting:

Attribute	Type	Values	Notes
period	integer	0, 1, 2, 3, 4	0 will be returned for games that have not started. 4 will be returned when a game is either complete or in the 4th quarter.
status	string	`{start_time}`, 1st Qtr, 2nd Qtr, Halftime, 3rd Qtr, 4th Qtr, Final	`{start_time}` looks something like "7:00 pm ET", which indicates that the game has not started yet.
time	string	`{time_in_period}`, " "	`${time_in_period}` looks something like "3:44". " " is an empty string that is returned when game has not started or is complete.

Get All Games

curl "https://api.balldontlie.io/v1/games" \
  -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const games = await api.nba.getGames();

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
games = api.nba.games.list()

{
  "data": [
    "id": 15907925,
    "date": "2025-01-05",
    "season": 2024,
    "status": "Final",
    "period": 4,
    "time": "Final",
    "postseason": false,
    "home_team_score": 115,
    "visitor_team_score": 105,
    "datetime": "2025-01-05T23:00:00.000Z",
    "home_q1": 29,
    "home_q2": 34,
    "home_q3": 28,
    "home_q4": 24,
    "home_ot1": null,
    "home_ot2": null,
    "home_ot3": null,
    "home_timeouts_remaining": 2,
    "home_in_bonus": true,
    "visitor_q1": 23,
    "visitor_q2": 25,
    "visitor_q3": 30,
    "visitor_q4": 27,
    "visitor_ot1": null,
    "visitor_ot2": null,
    "visitor_ot3": null,
    "visitor_timeouts_remaining": 2,
    "visitor_in_bonus": false,
    "home_team": {
      "id": 6,
      "conference": "East",
      "division": "Central",
      "city": "Cleveland",
      "name": "Cavaliers",
      "full_name": "Cleveland Cavaliers",
      "abbreviation": "CLE"
    },
    "visitor_team": {
      "id": 4,
      "conference": "East",
      "division": "Southeast",
      "city": "Charlotte",
      "name": "Hornets",
      "full_name": "Charlotte Hornets",
      "abbreviation": "CHA"
    },
    ...
  ],
  "meta": {
    "next_cursor": 25,
    "per_page": 25
  }
}

This endpoint retrieves all games.

HTTP Request

GET https://api.balldontlie.io/v1/games

Query Parameters

Parameter	Required	Description
cursor	false	The cursor, used for pagination
per_page	false	The number of results per page. Default to 25. Max is 100
dates	false	Returns games that match these dates. Dates should be formatted in `YYYY-MM-DD`. This should be an array: `?dates[]=2024-01-01&dates[]=2024-01-02`
seasons	false	Returns games that occurred in these seasons. This should be an array: `?seasons[]=2022&seasons[]=2023`
team_ids	false	Returns games for these team ids. This should be an array: `?team_ids[]=1&team_ids[]=2`
posteason	false	Returns playoffs games when set to true. Returns regular season games when set to false. Returns both when not specified
start_date	false	Returns games that occurred on or after this date. Date should be formatted in `YYYY-MM-DD`
end_date	false	Returns games that occurred on or before this date. Date should be formatted in `YYYY-MM-DD`

Get a Specific Game

curl "https://api.balldontlie.io/v1/games/<ID>" \
  -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const game = await api.nba.getGame(1);

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
game = api.nba.games.get(1)

{
  "data": {
    "id": 15907925,
    "date": "2025-01-05",
    "season": 2024,
    "status": "Final",
    "period": 4,
    "time": "Final",
    "postseason": false,
    "home_team_score": 115,
    "visitor_team_score": 105,
    "datetime": "2025-01-05T23:00:00.000Z",
    "home_q1": 29,
    "home_q2": 34,
    "home_q3": 28,
    "home_q4": 24,
    "home_ot1": null,
    "home_ot2": null,
    "home_ot3": null,
    "home_timeouts_remaining": 2,
    "home_in_bonus": true,
    "visitor_q1": 23,
    "visitor_q2": 25,
    "visitor_q3": 30,
    "visitor_q4": 27,
    "visitor_ot1": null,
    "visitor_ot2": null,
    "visitor_ot3": null,
    "visitor_timeouts_remaining": 2,
    "visitor_in_bonus": false,
    "home_team": {
      "id": 6,
      "conference": "East",
      "division": "Central",
      "city": "Cleveland",
      "name": "Cavaliers",
      "full_name": "Cleveland Cavaliers",
      "abbreviation": "CLE"
    },
    "visitor_team": {
      "id": 4,
      "conference": "East",
      "division": "Southeast",
      "city": "Charlotte",
      "name": "Hornets",
      "full_name": "Charlotte Hornets",
      "abbreviation": "CHA"
    }
  }
}

This endpoint retrieves a specific game.

HTTP Request

GET https://api.balldontlie.io/v1/games/<ID>

URL Parameters

Parameter	Required	Description
ID	true	The ID of the game to retrieve

Game Player Stats

Get All Stats

curl "https://api.balldontlie.io/v1/stats"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const stats = await api.nba.getStats();

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
stats = api.nba.stats.list()

{
  "data": [
    {
      "id": 14325883,
      "min": "38",
      "fgm": 10,
      "fga": 16,
      "fg_pct": 0.625,
      "fg3m": 0,
      "fg3a": 1,
      "fg3_pct": 0,
      "ftm": 11,
      "fta": 22,
      "ft_pct": 0.5,
      "oreb": 3,
      "dreb": 7,
      "reb": 10,
      "ast": 9,
      "stl": 2,
      "blk": 1,
      "turnover": 5,
      "pf": 1,
      "pts": 31,
      "player": {
        "id": 15,
        "first_name": "Giannis",
        "last_name": "Antetokounmpo",
        "position": "F",
        "height": "6-11",
        "weight": "243",
        "jersey_number": "34",
        "college": "Filathlitikos",
        "country": "Greece",
        "draft_year": 2013,
        "draft_round": 1,
        "draft_number": 15,
        "team_id": 17
      },
      "team": {
        "id": 17,
        "conference": "East",
        "division": "Central",
        "city": "Milwaukee",
        "name": "Bucks",
        "full_name": "Milwaukee Bucks",
        "abbreviation": "MIL"
      },
      "game": {
        "id": 1038184,
        "date": "2024-01-20",
        "season": 2023,
        "status": "Final",
        "period": 4,
        "time": "Final",
        "postseason": false,
        "home_team_score": 135,
        "visitor_team_score": 141,
        "home_team_id": 9,
        "visitor_team_id": 17
      }
    },
    ...
  ],
  "meta": {
    "next_cursor": 14325888,
    "per_page": 25
  }
}

This endpoint retrieves all stats.

HTTP Request

GET https://api.balldontlie.io/v1/stats

Query Parameters

You can combine query parameters. For example: ?seasons[]=2018&seasons[]=2015&player_ids[]=1&player_ids[]=2&postseason=true will return stats for player_ids 1 and 2 for the 2015-2016 and 2018-2019 postseason.

Parameter	Required	Description
cursor	false	The page number, used for pagination.
per_page	false	The number of results returned per call, used for pagination. Max 100.
player_ids	false	Returns stats for these player ids. This should be an array: `?player_ids[]=1&player_ids[]=2`
game_ids	false	Returns stat for these game ids. This should be an array: `?game_ids[]=1&game_ids[]=2`
dates	false	Returns stats that match these dates. Dates should be formatted in `YYYY-MM-DD`. This should be an array: `?dates[]=2024-01-01&dates[]=2024-01-02`
seasons	false	Returns stats that occurred in these seasons. This should be an array: `?seasons[]=2022&seasons[]=2023`
posteason	false	Returns playoff stats when set to true. Returns regular season stats when set to false. Returns both when not specified
start_date	false	Returns stats that occurred on or after this date. Date should be formatted in `YYYY-MM-DD`
end_date	false	Returns stats that occurred on or before this date. Date should be formatted in `YYYY-MM-DD`

Season Averages

Get Averages

There are many types of season averages you can retrieve. You must specify a category in the route and an additional type as a query parameter. For example: https://api.balldontlie.io/nba/v1/season_averages/general?season=2024&season_type=regular&type=base will return general season averages for the 2024 season. Note the category in this example is general and the type is base.

Here are the available pairing options between category and type:

Category	Type
general	base
general	advanced
general	usage
general	scoring
general	defense
general	misc
clutch	advanced
clutch	base
clutch	misc
clutch	scoring
clutch	usage
defense	2_pointers
defense	3_pointers
defense	greater_than_15ft
defense	less_than_10ft
defense	less_than_6ft
defense	overall
shooting	5ft_range
shooting	by_zone

Regardless of the category + type combination, all data is returned in the same shape. The only difference is the stats property which will contain attribute names that are specific to the requested category + type.

curl "https://api.balldontlie.io/v1/season_averages/shooting?season=2024&season_type=regular&type=5ft_range&player_ids[]=246"

{
  "data": [
    {
      "player": {
        "id": 246,
        "first_name": "Nikola",
        "last_name": "Jokic",
        "position": "C",
        "height": "6-11",
        "weight": "284",
        "jersey_number": "15",
        "college": "Mega Basket",
        "country": "Serbia",
        "draft_year": 2014,
        "draft_round": 2,
        "draft_number": 41
      },
      "season": 2024,
      "season_type": "regular",
      "stats": {
        "40+_ft._fga": 0.4,
        "40+_ft._fgm": 0,
        "5-9_ft._fga": 5.1,
        "5-9_ft._fgm": 2.9,
        "10-14_ft._fga": 1.4,
        "10-14_ft._fgm": 0.6,
        "15-19_ft._fga": 0.8,
        "15-19_ft._fgm": 0.4,
        "20-24_ft._fga": 0.7,
        "20-24_ft._fgm": 0.4,
        "25-29_ft._fga": 3.5,
        "25-29_ft._fgm": 1.7,
        "30-34_ft._fga": 0.1,
        "30-34_ft._fgm": 0,
        "35-39_ft._fga": 0,
        "35-39_ft._fgm": 0,
        "40+_ft._fg_pct": 0.118,
        "5-9_ft._fg_pct": 0.571,
        "10-14_ft._fg_pct": 0.424,
        "15-19_ft._fg_pct": 0.514,
        "20-24_ft._fg_pct": 0.5,
        "25-29_ft._fg_pct": 0.488,
        "30-34_ft._fg_pct": 0,
        "35-39_ft._fg_pct": 0,
        "less_than_5_ft._fga": 7.7,
        "less_than_5_ft._fgm": 5.3,
        "less_than_5_ft._fg_pct": 0.684
      }
    }
  ],
  "meta": {
    "per_page": 25
  }
}

HTTP Request

GET https://api.balldontlie.io/v1/season_averages/shooting?season=2024&season_type=regular&type=5ft_range&player_ids[]=246

Route Parameters

Parameter	Required	Description
category	true	Available options: general, clutch, defense, shooting

Query Parameters

Parameter	Required	Description
season_type	true	Availble options: regular, playoffs, ist, playin
type	true	Available options: advanced, base, misc, scoring, usage, 2_pointers, 3_pointers, greater_than_15ft, less_than_10ft, less_than_6ft, overall, by_zone, 5ft_range
season	true	Returns season averages for this season
player_ids	false	Returns season averages for these players. This should be an array: `?player_ids[]=1&player_ids[]=2`

Game Advanced Stats

Attributes

These response attributes are worth noting.

Attribute	Type	Notes
pie	float	Player Impact Estimate (PIE) measures a player's overall statistical contribution against the total statistics in games they play in. PIE yields results which are comparable to other advanced statistics (e.g. PER) using a simple formula.
pace	float	The number of possessions per 48 minutes.
assist_percentage	float	The percentage of teammate field goals a player assisted on while they were on the floor
assist_ratio	float	Assist Ratio is the number of assists a player averages per 100 possessions used
assist_to_turnover	float	The number of assists compared to the number of turnovers they have committed
defensive_rating	float	The number of points per 100 possessions that the team allows while that individual player is on the court.
defensive_rebound_percentage	float	The percentage of available defensive rebounds a player obtains while on the floor
effective_field_goal_percentage	float	Measures field goal percentage adjusting for made 3-point field goals being 1.5 times more valuable than made 2-point field goals.
net_rating	float	The team's point differential per 100 possessions while the player is on court.
offensive_rating	float	Team points scored per 100 possessions while the player is on court
offensive_rebound_percentage	float	The percentage of available offensive rebounds a player obtains while on the floor
rebound_percentage	float	The percentage of available rebounds a player grabbed while on the floor
true_shooting_percentage	float	A shooting percentage that factors in the value of three-point field goals and free throws in addition to conventional two-point field goals
turnover_ratio	float	The number of turnovers a player averages per 100 possessions used
usage_percentage	float	The percentage of team plays used by a player when they are on the floor

Get All Advanced Stats

curl "https://api.balldontlie.io/v1/stats/advanced"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const stats = await api.nba.getAdvancedStats({ seasons: [2023] });

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
stats = api.nba.advanced_stats.list()

{
  "data": [
    {
      "id": 1,
      "pie": -0.031,
      "pace": 98.08,
      "assist_percentage": 0.15,
      "assist_ratio": 25,
      "assist_to_turnover": 0.75,
      "defensive_rating": 100,
      "defensive_rebound_percentage": 0.132,
      "effective_field_goal_percentage": 0,
      "net_rating": -20,
      "offensive_rating": 80,
      "offensive_rebound_percentage": 0.069,
      "rebound_percentage": 0.104,
      "true_shooting_percentage": 0.087,
      "turnover_ratio": 33.3,
      "usage_percentage": 0.127,
      "player": {
        "id": 2970,
        "first_name": "Olden",
        "last_name": "Polynice",
        "position": "",
        "height": "7-0",
        "weight": "250",
        "jersey_number": "0",
        "college": "Virginia",
        "country": "USA",
        "draft_year": 1987,
        "draft_round": 1,
        "draft_number": 8,
        "team_id": 26
      },
      "team": {
        "id": 26,
        "conference": "West",
        "division": "Pacific",
        "city": "Sacramento",
        "name": "Kings",
        "full_name": "Sacramento Kings",
        "abbreviation": "SAC"
      },
      "game": {
        "id": 3524,
        "date": "1996-11-01",
        "season": 1996,
        "status": "Final",
        "period": 4,
        "time": " ",
        "postseason": false,
        "home_team_score": 96,
        "visitor_team_score": 85,
        "home_team_id": 11,
        "visitor_team_id": 26
      }
    },
    ...
  ],
  "meta": {
    "next_cursor": 14325888,
    "per_page": 25
  }
}

This endpoint retrieves all advanced stats.

HTTP Request

GET https://api.balldontlie.io/v1/stats/advanced

Query Parameters

You can combine query parameters. For example: ?seasons[]=2018&seasons[]=2015&player_ids[]=1&player_ids[]=2&postseason=true will return advanced stats for player_ids 1 and 2 for the 2015-2016 and 2018-2019 postseason.

Parameter	Required	Description
cursor	false	The page number, used for pagination.
per_page	false	The number of results returned per call, used for pagination. Max 100.
player_ids	false	Returns stats for these player ids. This should be an array: `?player_ids[]=1&player_ids[]=2`
game_ids	false	Returns stat for these game ids. This should be an array: `?game_ids[]=1&game_ids[]=2`
dates	false	Returns stats that match these dates. Dates should be formatted in `YYYY-MM-DD`. This should be an array: `?dates[]=2024-01-01&dates[]=2024-01-02`
seasons	false	Returns stats that occurred in these seasons. This should be an array: `?seasons[]=2022&seasons[]=2023`
posteason	false	Returns playoff stats when set to true. Returns regular season stats when set to false. Returns both when not specified
start_date	false	Returns stats that occurred on or after this date. Date should be formatted in `YYYY-MM-DD`
end_date	false	Returns stats that occurred on or before this date. Date should be formatted in `YYYY-MM-DD`

Box Scores

Get Live Box Scores

curl "https://api.balldontlie.io/v1/box_scores/live"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const boxScores = await api.nba.getLiveBoxScores();

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
box_scores = api.nba.box_scores.get_live()

{
  "data": [
    {
      "date": "2024-02-07",
      "season": 2023,
      "status": "Final",
      "period": 4,
      "time": "Final",
      "postseason": false,
      "home_team_score": 117,
      "visitor_team_score": 123,
      "home_team": {
        "id": 4,
        "conference": "East",
        "division": "Southeast",
        "city": "Charlotte",
        "name": "Hornets",
        "full_name": "Charlotte Hornets",
        "abbreviation": "CHA",
        "players": [
          {
            "min": "23",
            "fgm": 1,
            "fga": 2,
            "fg_pct": 0.5,
            "fg3m": 0,
            "fg3a": 1,
            "fg3_pct": 0,
            "ftm": 1,
            "fta": 2,
            "ft_pct": 0.5,
            "oreb": 0,
            "dreb": 3,
            "reb": 3,
            "ast": 3,
            "stl": 0,
            "blk": 1,
            "turnover": 1,
            "pf": 1,
            "pts": 3,
            "player": {
              "id": 56677866,
              "first_name": "Leaky",
              "last_name": "Black",
              "position": "F",
              "height": "6-6",
              "weight": "209",
              "jersey_number": "12",
              "college": "North Carolina",
              "country": "USA",
              "draft_year": null,
              "draft_round": null,
              "draft_number": null
            }
          },
          ...
        ]
      },
      "visitor_team": {
        "id": 28,
        "conference": "East",
        "division": "Atlantic",
        "city": "Toronto",
        "name": "Raptors",
        "full_name": "Toronto Raptors",
        "abbreviation": "TOR",
        "players": [
          {
            "min": "15",
            "fgm": 2,
            "fga": 3,
            "fg_pct": 0.6666667,
            "fg3m": 0,
            "fg3a": 0,
            "fg3_pct": 0,
            "ftm": 0,
            "fta": 0,
            "ft_pct": 0,
            "oreb": 3,
            "dreb": 5,
            "reb": 8,
            "ast": 2,
            "stl": 1,
            "blk": 0,
            "turnover": 1,
            "pf": 2,
            "pts": 4,
            "player": {
                "id": 489,
                "first_name": "Thaddeus",
                "last_name": "Young",
                "position": "F",
                "height": "6-8",
                "weight": "225",
                "jersey_number": "21",
                "college": "Georgia Tech",
                "country": "USA",
                "draft_year": 2007,
                "draft_round": 1,
                "draft_number": 12
            }
          },
          ...
        ]
      }
    },
  ...
  ]
}

This endpoint retrieves all live box scores.

HTTP Request

GET https://api.balldontlie.io/v1/box_scores/live

Get Box Scores

curl "https://api.balldontlie.io/v1/box_scores"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const scores = await api.nba.getBoxScores("2024-02-07");

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
scores = api.nba.box_scores.get_by_date(date="2024-02-07")

{
  "data": [
    {
      "date": "2024-02-07",
      "season": 2023,
      "status": "Final",
      "period": 4,
      "time": "Final",
      "postseason": false,
      "home_team_score": 117,
      "visitor_team_score": 123,
      "home_team": {
        "id": 4,
        "conference": "East",
        "division": "Southeast",
        "city": "Charlotte",
        "name": "Hornets",
        "full_name": "Charlotte Hornets",
        "abbreviation": "CHA",
        "players": [
          {
            "min": "23",
            "fgm": 1,
            "fga": 2,
            "fg_pct": 0.5,
            "fg3m": 0,
            "fg3a": 1,
            "fg3_pct": 0,
            "ftm": 1,
            "fta": 2,
            "ft_pct": 0.5,
            "oreb": 0,
            "dreb": 3,
            "reb": 3,
            "ast": 3,
            "stl": 0,
            "blk": 1,
            "turnover": 1,
            "pf": 1,
            "pts": 3,
            "player": {
              "id": 56677866,
              "first_name": "Leaky",
              "last_name": "Black",
              "position": "F",
              "height": "6-6",
              "weight": "209",
              "jersey_number": "12",
              "college": "North Carolina",
              "country": "USA",
              "draft_year": null,
              "draft_round": null,
              "draft_number": null
            }
          },
          ...
        ]
      },
      "visitor_team": {
        "id": 28,
        "conference": "East",
        "division": "Atlantic",
        "city": "Toronto",
        "name": "Raptors",
        "full_name": "Toronto Raptors",
        "abbreviation": "TOR",
        "players": [
          {
            "min": "15",
            "fgm": 2,
            "fga": 3,
            "fg_pct": 0.6666667,
            "fg3m": 0,
            "fg3a": 0,
            "fg3_pct": 0,
            "ftm": 0,
            "fta": 0,
            "ft_pct": 0,
            "oreb": 3,
            "dreb": 5,
            "reb": 8,
            "ast": 2,
            "stl": 1,
            "blk": 0,
            "turnover": 1,
            "pf": 2,
            "pts": 4,
            "player": {
                "id": 489,
                "first_name": "Thaddeus",
                "last_name": "Young",
                "position": "F",
                "height": "6-8",
                "weight": "225",
                "jersey_number": "21",
                "college": "Georgia Tech",
                "country": "USA",
                "draft_year": 2007,
                "draft_round": 1,
                "draft_number": 12
            }
          },
          ...
        ]
      }
    },
  ...
  ]
}

This endpoint retrieves all box scores.

HTTP Request

GET https://api.balldontlie.io/v1/box_scores

Query Parameters

Parameter	Required	Description
date	true	Returns all box scores for this date. The date should be formatted in `YYYY-MM-DD`

Active Players

Get All Active Players

curl "https://api.balldontlie.io/v1/players/active" \
  -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const players = await api.nba.getActivePlayers();

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
players = api.nba.players.list_active()

{
  "data": [
    {
        "id": 19,
        "first_name": "Stephen",
        "last_name": "Curry",
        "position": "G",
        "height": "6-2",
        "weight": "185",
        "jersey_number": "30",
        "college": "Davidson",
        "country": "USA",
        "draft_year": 2009,
        "draft_round": 1,
        "draft_number": 7,
        "team": {
            "id": 10,
            "conference": "West",
            "division": "Pacific",
            "city": "Golden State",
            "name": "Warriors",
            "full_name": "Golden State Warriors",
            "abbreviation": "GSW"
        }
    },
    ...
  ],
  "meta": {
    "next_cursor": 25,
    "per_page": 25
  }
}

This endpoint retrieves all active players.

HTTP Request

GET https://api.balldontlie.io/v1/players/active

Query Parameters

Parameter	Required	Description
cursor	false	The cursor, used for pagination
per_page	false	The number of results per page. Default to 25. Max is 100
search	false	Returns players whose first or last name matches this value. For example, `?search=davis` will return players that have 'davis' in their first or last name.
first_name	false	Returns players whose first name matches this value. For example, `?search=anthony` will return players that have 'anthony' in their first name.
last_name	false	Returns players whose last name matches this value. For example, `?search=davis` will return players that have 'davis' in their last name.
team_ids	false	Returns players that belong to these team ids. This should be an array: `?team_ids[]=1&team_ids[]=2`
player_ids	false	Returns players that match these ids. This should be an array: `?player_ids[]=1&player_ids[]=2`

Player Injuries

Get All Player Injuries

curl "https://api.balldontlie.io/v1/player_injuries" \
  -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const injuries = await api.nba.getPlayerInjuries();

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
injuries = api.nba.injuries.list()

{
  "data": [
    {
      "player": {
        "id": 56677838,
        "first_name": "Kobe",
        "last_name": "Bufkin",
        "position": "G",
        "height": "6-4",
        "weight": "195",
        "jersey_number": "4",
        "college": "Michigan",
        "country": "USA",
        "draft_year": 2023,
        "draft_round": 1,
        "draft_number": 15,
        "team_id": 1
      },
      "return_date": "Nov 17",
      "description": "Nov 16: Bufkin (shoulder) is listed as doubtful for Sunday's game against the Trail Blazers.",
      "status": "Out"
    }
  ],
  "meta": { "next_cursor": 62089, "per_page": 25 }
}

This endpoint retrieves all player injuries.

HTTP Request

GET https://api.balldontlie.io/v1/player_injuries

Query Parameters

Parameter	Required	Description
cursor	false	The cursor, used for pagination
per_page	false	The number of results per page. Default to 25. Max is 100
team_ids	false	Returns players that belong to these team ids. This should be an array: `?team_ids[]=1&team_ids[]=2`
player_ids	false	Returns players that match these ids. This should be an array: `?player_ids[]=1&player_ids[]=2`

Team Standings

Get Team Standings

curl "https://api.balldontlie.io/v1/standings?season=2023" \
  -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const standings = await api.nba.getStandings({ season: 2023 });

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
standings = api.nba.standings.get(season=2023)

{
  "data": [
    {
        "team": {
            "id": 10,
            "conference": "West",
            "division": "Pacific",
            "city": "Golden State",
            "name": "Warriors",
            "full_name": "Golden State Warriors",
            "abbreviation": "GSW"
        },
        "conference_record": "10-1",
        "conference_rank": 1,
        "division_record": "5-0",
        "division_rank": 1,
        "wins": 11,
        "losses": 1,
        "home_record": "8-0",
        "road_record": "2-1",
        "season": 2023
    },
    ...
  ]
}

This endpoint retrieves regular season team standings.

HTTP Request

GET https://api.balldontlie.io/v1/standings

Query Parameters

Parameter	Required	Description
season	true	Returns regular season standings for the specified season. For example, `?season=2023` will return the team standings for the 2023-24 season.

Leaders

Get Leaders

curl "https://api.balldontlie.io/v1/leaders?season=2023&stat_type=pts" \
  -H "Authorization: YOUR_API_KEY"

import { BalldontlieAPI } from "@balldontlie/sdk";

const api = new BalldontlieAPI({ apiKey: "YOUR_API_KEY" });
const leaders = await api.nba.getLeaders({
  stat_type: "pts",
  season: 2023,
});

from balldontlie import BalldontlieAPI

api = BalldontlieAPI(api_key="YOUR_API_KEY")
leaders = api.nba.leaders.get(stat_type="pts", season=2023)

{
  "data": [
    {
      "player": {
        "id": 19,
        "first_name": "Stephen",
        "last_name": "Curry",
        "position": "G",
        "height": "6-2",
        "weight": "185",
        "jersey_number": "30",
        "college": "Davidson",
        "country": "USA",
        "draft_year": 2009,
        "draft_round": 1,
        "draft_number": 7,
        "team_id": 10,
      },
      "value": 32.3,
      "stat_type": "pts",
      "rank": 1,
      "season": 2023,
      "games_played": 34
    },
    ...
  ]
}

This endpoint retrieves regular season per game leaders for specific stat categories.

HTTP Request

GET https://api.balldontlie.io/v1/leaders

Query Parameters

Parameter	Required	Description
stat_type	true	Returns leaders for the specified stat_type. Valid stat_types are `reb`, `dreb`, `tov`, `ast`, `oreb`, `min`, `pts`, `stl`, `blk`. For example, `?stat_type=pts` will return the current points per game leaders
season	true	Returns leaders for the specified season

Betting Odds

Get Betting Odds

curl "https://api.balldontlie.io/v2/odds?dates[]=2025-01-15" \
  -H "Authorization: YOUR_API_KEY"

const axios = require("axios");

const response = await axios.get("https://api.balldontlie.io/v2/odds", {
  params: {
    "dates[]": "2025-01-15",
  },
  headers: {
    Authorization: "YOUR_API_KEY",
  },
});

console.log(response.data);

import requests

response = requests.get(
    'https://api.balldontlie.io/v2/odds',
    params={'dates[]': '2025-01-15'},
    headers={'Authorization': 'YOUR_API_KEY'}
)

print(response.json())

{
  "data": [
    {
      "id": 1105,
      "game_id": 18446819,
      "vendor": "draftkings",
      "spread_home_value": "-7.5",
      "spread_home_odds": -120,
      "spread_away_value": "7.5",
      "spread_away_odds": -110,
      "moneyline_home_odds": -330,
      "moneyline_away_odds": 240,
      "total_value": "228.5",
      "total_over_odds": -115,
      "total_under_odds": -115,
      "updated_at": "2025-10-21T23:46:11.875Z"
    },
    {
      "id": 1106,
      "game_id": 18446820,
      "vendor": "draftkings",
      "spread_home_value": "2.5",
      "spread_home_odds": -112,
      "spread_away_value": "-2.5",
      "spread_away_odds": -108,
      "moneyline_home_odds": 120,
      "moneyline_away_odds": -142,
      "total_value": "227.5",
      "total_over_odds": -108,
      "total_under_odds": -112,
      "updated_at": "2025-10-21T23:46:11.875Z"
    },
    {
      "id": 1051,
      "game_id": 18446819,
      "vendor": "caesars",
      "spread_home_value": "-7.5",
      "spread_home_odds": -105,
      "spread_away_value": "7.5",
      "spread_away_odds": -125,
      "moneyline_home_odds": -320,
      "moneyline_away_odds": 240,
      "total_value": "228.5",
      "total_over_odds": -115,
      "total_under_odds": -115,
      "updated_at": "2025-10-21T23:45:55.739Z"
    },
    {
      "id": 1052,
      "game_id": 18446820,
      "vendor": "caesars",
      "spread_home_value": "2.5",
      "spread_home_odds": -105,
      "spread_away_value": "-2.5",
      "spread_away_odds": -115,
      "moneyline_home_odds": 122,
      "moneyline_away_odds": -145,
      "total_value": "227",
      "total_over_odds": -105,
      "total_under_odds": -115,
      "updated_at": "2025-10-21T23:45:55.739Z"
    },
    {
      "id": 1414,
      "game_id": 18446820,
      "vendor": "fanduel",
      "spread_home_value": "2.5",
      "spread_home_odds": -108,
      "spread_away_value": "-2.5",
      "spread_away_odds": -112,
      "moneyline_home_odds": 120,
      "moneyline_away_odds": -142,
      "total_value": "226.5",
      "total_over_odds": -112,
      "total_under_odds": -108,
      "updated_at": "2025-10-21T23:45:41.957Z"
    },
    {
      "id": 153881,
      "game_id": 18446819,
      "vendor": "bet365",
      "spread_home_value": "-6.5",
      "spread_home_odds": -110,
      "spread_away_value": "6.5",
      "spread_away_odds": -110,
      "moneyline_home_odds": -260,
      "moneyline_away_odds": 210,
      "total_value": "227.5",
      "total_over_odds": -110,
      "total_under_odds": -110,
      "updated_at": "2025-10-21T23:45:39.624Z"
    },
    {
      "id": 157016,
      "game_id": 18446820,
      "vendor": "bet365",
      "spread_home_value": "2.5",
      "spread_home_odds": -110,
      "spread_away_value": "-2.5",
      "spread_away_odds": -110,
      "moneyline_home_odds": 120,
      "moneyline_away_odds": -140,
      "total_value": "226.5",
      "total_over_odds": -110,
      "total_under_odds": -110,
      "updated_at": "2025-10-21T23:45:39.624Z"
    },
    {
      "id": 1346,
      "game_id": 18446819,
      "vendor": "espnbet",
      "spread_home_value": "-7.5",
      "spread_home_odds": -115,
      "spread_away_value": "7.5",
      "spread_away_odds": -105,
      "moneyline_home_odds": -330,
      "moneyline_away_odds": 240,
      "total_value": "227.5",
      "total_over_odds": 110,
      "total_under_odds": -140,
      "updated_at": "2025-10-21T23:45:26.583Z"
    },
    {
      "id": 1347,
      "game_id": 18446820,
      "vendor": "espnbet",
      "spread_home_value": "2.5",
      "spread_home_odds": -105,
      "spread_away_value": "-2.5",
      "spread_away_odds": -115,
      "moneyline_home_odds": 120,
      "moneyline_away_odds": -140,
      "total_value": "227.5",
      "total_over_odds": -110,
      "total_under_odds": -110,
      "updated_at": "2025-10-21T23:45:26.583Z"
    },
    {
      "id": 1067,
      "game_id": 18446819,
      "vendor": "betmgm",
      "spread_home_value": "-6.5",
      "spread_home_odds": -125,
      "spread_away_value": "6.5",
      "spread_away_odds": -105,
      "moneyline_home_odds": -285,
      "moneyline_away_odds": 210,
      "total_value": "227.5",
      "total_over_odds": -110,
      "total_under_odds": -115,
      "updated_at": "2025-10-21T23:45:18.356Z"
    },
    {
      "id": 1068,
      "game_id": 18446820,
      "vendor": "betmgm",
      "spread_home_value": "2.5",
      "spread_home_odds": -115,
      "spread_away_value": "-2.5",
      "spread_away_odds": -105,
      "moneyline_home_odds": 115,
      "moneyline_away_odds": -140,
      "total_value": "227.5",
      "total_over_odds": -110,
      "total_under_odds": -110,
      "updated_at": "2025-10-21T23:45:18.356Z"
    },
    {
      "id": 1413,
      "game_id": 18446819,
      "vendor": "fanduel",
      "spread_home_value": "-6.5",
      "spread_home_odds": -108,
      "spread_away_value": "6.5",
      "spread_away_odds": -112,
      "moneyline_home_odds": -250,
      "moneyline_away_odds": 205,
      "total_value": "225.5",
      "total_over_odds": -108,
      "total_under_odds": -112,
      "updated_at": "2025-10-21T23:42:41.908Z"
    }
  ],
  "meta": {
    "per_page": 25
  }
}

This endpoint retrieves betting odds for NBA games. At least one of dates or game_ids must be provided.

Available vendors include: betmgm, fanduel, draftkings, bet365, caesars, and espnbet.

HTTP Request

GET https://api.balldontlie.io/v2/odds

Query Parameters

Parameter	Required	Description
cursor	false	The cursor, used for pagination
per_page	false	The number of results per page. Default to 25. Max is 100
dates	false	Returns odds for games on these dates. Dates should be formatted in `YYYY-MM-DD`. This should be an array: `?dates[]=2025-01-15&dates[]=2025-01-16`
game_ids	false	Returns odds for these game ids. This should be an array: `?game_ids[]=15907925&game_ids[]=15907926`

Player Props

Get Player Props

curl "https://api.balldontlie.io/v2/odds/player_props?game_id=18447073" \
  -H "Authorization: YOUR_API_KEY"

const axios = require("axios");

const response = await axios.get(
  "https://api.balldontlie.io/v2/odds/player_props",
  {
    params: {
      game_id: 18447073,
    },
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);

console.log(response.data);

import requests

response = requests.get(
    'https://api.balldontlie.io/v2/odds/player_props',
    params={'game_id': 18447073},
    headers={'Authorization': 'YOUR_API_KEY'}
)

print(response.json())

{
  "data": [
    {
      "id": 15777190,
      "game_id": 18447073,
      "player_id": 246,
      "vendor": "draftkings",
      "prop_type": "points",
      "line_value": "18",
      "market": {
        "type": "milestone",
        "odds": -1960
      },
      "updated_at": "2025-11-24T23:46:46.653Z"
    },
    {
      "id": 15777199,
      "game_id": 18447073,
      "player_id": 246,
      "vendor": "draftkings",
      "prop_type": "points",
      "line_value": "30.5",
      "market": {
        "type": "over_under",
        "over_odds": -111,
        "under_odds": -115
      },
      "updated_at": "2025-11-24T23:46:46.653Z"
    },
    {
      "id": 15777202,
      "game_id": 18447073,
      "player_id": 246,
      "vendor": "draftkings",
      "prop_type": "points_first3min",
      "line_value": "3",
      "market": {
        "type": "milestone",
        "odds": 139
      },
      "updated_at": "2025-11-24T23:46:46.653Z"
    }
  ],
  "meta": {
    "next_cursor": 15777214,
    "per_page": 25
  }
}

This endpoint retrieves live player prop betting data for a specific NBA game. Player props include predictions for individual player performance like points, rebounds, assists, and more.

The API supports two market types:

over_under: Traditional over/under markets where users can bet on whether a player will go over or under a specific line value
milestone: Milestone markets where users bet on whether a player will reach a specific achievement (e.g., scoring exactly 30+ points)

Available vendors include: draftkings, betway, betrivers, and ballybet. More vendors coming soon!

HTTP Request

GET https://api.balldontlie.io/v2/odds/player_props

Query Parameters

Parameter	Required	Description
game_id	true	The game ID to retrieve player props for
player_id	false	Filter props for a specific player
prop_type	false	Filter by prop type. See supported prop types below.
cursor	false	The cursor, used for pagination
per_page	false	The number of results per page. Default to 25. Max is 100

Supported Prop Types

The following prop_type values are supported:

Prop Type	Description
points	Total points
rebounds	Total rebounds
assists	Total assists
threes	Three-pointers made
steals	Total steals
blocks	Total blocks
points_1q	Points in first quarter
rebounds_1q	Rebounds in first quarter
assists_1q	Assists in first quarter
points_first3min	Points in first 3 minutes
rebounds_first3min	Rebounds in first 3 minutes
assists_first3min	Assists in first 3 minutes

Response Attributes

Attribute	Type	Description
id	integer	Unique identifier for the prop
game_id	integer	The game this prop belongs to
player_id	integer	The player this prop is for
vendor	string	The sportsbook offering this prop
prop_type	string	The type of prop (e.g., "points", "rebounds", "assists", "threes")
line_value	string	The line value for the prop
market	object	Market information - either over_under or milestone type
updated_at	string	ISO 8601 timestamp of when this prop was last updated

Contracts

Get Team Contracts

curl "https://api.balldontlie.io/v1/contracts/teams?team_id=5&season=2025" \
  -H "Authorization: YOUR_API_KEY"

const axios = require("axios");

const response = await axios.get(
  "https://api.balldontlie.io/v1/contracts/teams",
  {
    params: {
      team_id: 5,
      season: 2025,
    },
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);

console.log(response.data);

import requests

response = requests.get(
    'https://api.balldontlie.io/v1/contracts/teams',
    params={'team_id': 5, 'season': 2025},
    headers={'Authorization': 'YOUR_API_KEY'}
)

print(response.json())

{
  "data": [
    {
      "id": 6251,
      "player_id": 17896065,
      "season": 2025,
      "team_id": 5,
      "cap_hit": 25000000,
      "total_cash": 25000000,
      "base_salary": 25000000,
      "rank": 0,
      "player": {
        "id": 17896065,
        "first_name": "Josh",
        "last_name": "Giddey",
        "position": "G",
        "height": "6-7",
        "weight": "216",
        "jersey_number": "3",
        "college": "NBA Global Academy",
        "country": "Australia",
        "draft_year": 2021,
        "draft_round": 1,
        "draft_number": 6,
        "team_id": 5
      },
      "team": {
        "id": 5,
        "conference": "East",
        "division": "Central",
        "city": "Chicago",
        "name": "Bulls",
        "full_name": "Chicago Bulls",
        "abbreviation": "CHI"
      }
    },
    {
      "id": 6263,
      "player_id": 460,
      "season": 2025,
      "team_id": 5,
      "cap_hit": 21481481,
      "total_cash": 21481481,
      "base_salary": 21481481,
      "rank": 85,
      "player": {
        "id": 460,
        "first_name": "Nikola",
        "last_name": "Vucevic",
        "position": "C",
        "height": "6-9",
        "weight": "260",
        "jersey_number": "9",
        "college": "Southern California",
        "country": "Montenegro",
        "draft_year": 2011,
        "draft_round": 1,
        "draft_number": 16,
        "team_id": 5
      },
      "team": {
        "id": 5,
        "conference": "East",
        "division": "Central",
        "city": "Chicago",
        "name": "Bulls",
        "full_name": "Chicago Bulls",
        "abbreviation": "CHI"
      }
    },
    {
      "id": 6280,
      "player_id": 102,
      "season": 2025,
      "team_id": 5,
      "cap_hit": 18080496,
      "total_cash": 18080496,
      "base_salary": 18080496,
      "rank": 102,
      "player": {
        "id": 102,
        "first_name": "Zach",
        "last_name": "Collins",
        "position": "F-C",
        "height": "6-9",
        "weight": "250",
        "jersey_number": "12",
        "college": "Gonzaga",
        "country": "USA",
        "draft_year": 2017,
        "draft_round": 1,
        "draft_number": 10,
        "team_id": 5
      },
      "team": {
        "id": 5,
        "conference": "East",
        "division": "Central",
        "city": "Chicago",
        "name": "Bulls",
        "full_name": "Chicago Bulls",
        "abbreviation": "CHI"
      }
    },
    {
      "id": 6281,
      "player_id": 3547248,
      "season": 2025,
      "team_id": 5,
      "cap_hit": 18000000,
      "total_cash": 18000000,
      "base_salary": 18000000,
      "rank": 103,
      "player": {
        "id": 3547248,
        "first_name": "Patrick",
        "last_name": "Williams",
        "position": "F",
        "height": "6-6",
        "weight": "215",
        "jersey_number": "44",
        "college": "Florida State",
        "country": "USA",
        "draft_year": 2020,
        "draft_round": 1,
        "draft_number": 4,
        "team_id": 5
      },
      "team": {
        "id": 5,
        "conference": "East",
        "division": "Central",
        "city": "Chicago",
        "name": "Bulls",
        "full_name": "Chicago Bulls",
        "abbreviation": "CHI"
      }
    },
    {
      "id": 6282,
      "player_id": 221,
      "season": 2025,
      "team_id": 5,
      "cap_hit": 17991071,
      "total_cash": 17991071,
      "base_salary": 17991071,
      "rank": 104,
      "player": {
        "id": 221,
        "first_name": "Kevin",
        "last_name": "Huerter",
        "position": "G",
        "height": "6-6",
        "weight": "198",
        "jersey_number": "13",
        "college": "Maryland",
        "country": "USA",
        "draft_year": 2018,
        "draft_round": 1,
        "draft_number": 19,
        "team_id": 5
      },
      "team": {
        "id": 5,
        "conference": "East",
        "division": "Central",
        "city": "Chicago",
        "name": "Bulls",
        "full_name": "Chicago Bulls",
        "abbreviation": "CHI"
      }
    },
    ...
  ]
}

This endpoint retrieves all player contracts for a specific team and season. If the season parameter is not provided, it defaults to the current season.

HTTP Request

GET https://api.balldontlie.io/v1/contracts/teams

Query Parameters

Parameter	Required	Description
team_id	true	The team ID
season	false	The season year (e.g., 2025). Defaults to current season if not specified.

Get Player Contracts

curl "https://api.balldontlie.io/v1/contracts/players?player_id=140" \
  -H "Authorization: YOUR_API_KEY"

const axios = require("axios");

const response = await axios.get(
  "https://api.balldontlie.io/v1/contracts/players",
  {
    params: {
      player_id: 140,
    },
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);

console.log(response.data);

import requests

response = requests.get(
    'https://api.balldontlie.io/v1/contracts/players',
    params={'player_id': 140},
    headers={'Authorization': 'YOUR_API_KEY'}
)

print(response.json())

{
  "data": [
    {
      "id": 7391,
      "player_id": 140,
      "season": 2027,
      "team_id": 11,
      "cap_hit": 46097561,
      "total_cash": 46097561,
      "base_salary": 46097561,
      "rank": 24,
      "player": {
        "id": 140,
        "first_name": "Kevin",
        "last_name": "Durant",
        "position": "F",
        "height": "6-11",
        "weight": "240",
        "jersey_number": "7",
        "college": "Texas",
        "country": "USA",
        "draft_year": 2007,
        "draft_round": 1,
        "draft_number": 2,
        "team_id": 11
      },
      "team": {
        "id": 11,
        "conference": "West",
        "division": "Southwest",
        "city": "Houston",
        "name": "Rockets",
        "full_name": "Houston Rockets",
        "abbreviation": "HOU"
      }
    },
    {
      "id": 7076,
      "player_id": 140,
      "season": 2026,
      "team_id": 11,
      "cap_hit": 43902439,
      "total_cash": 43902439,
      "base_salary": 43902439,
      "rank": 28,
      "player": {
        "id": 140,
        "first_name": "Kevin",
        "last_name": "Durant",
        "position": "F",
        "height": "6-11",
        "weight": "240",
        "jersey_number": "7",
        "college": "Texas",
        "country": "USA",
        "draft_year": 2007,
        "draft_round": 1,
        "draft_number": 2,
        "team_id": 11
      },
      "team": {
        "id": 11,
        "conference": "West",
        "division": "Southwest",
        "city": "Houston",
        "name": "Rockets",
        "full_name": "Houston Rockets",
        "abbreviation": "HOU"
      }
    },
    {
      "id": 6182,
      "player_id": 140,
      "season": 2025,
      "team_id": 11,
      "cap_hit": 54708609,
      "total_cash": 53282608,
      "base_salary": 53282608,
      "rank": 4,
      "player": {
        "id": 140,
        "first_name": "Kevin",
        "last_name": "Durant",
        "position": "F",
        "height": "6-11",
        "weight": "240",
        "jersey_number": "7",
        "college": "Texas",
        "country": "USA",
        "draft_year": 2007,
        "draft_round": 1,
        "draft_number": 2,
        "team_id": 11
      },
      "team": {
        "id": 11,
        "conference": "West",
        "division": "Southwest",
        "city": "Houston",
        "name": "Rockets",
        "full_name": "Houston Rockets",
        "abbreviation": "HOU"
      }
    },
    {
      "id": 5734,
      "player_id": 140,
      "season": 2024,
      "team_id": 24,
      "cap_hit": 51179021,
      "total_cash": 49856021,
      "base_salary": 49856021,
      "rank": 4,
      "player": {
        "id": 140,
        "first_name": "Kevin",
        "last_name": "Durant",
        "position": "F",
        "height": "6-11",
        "weight": "240",
        "jersey_number": "7",
        "college": "Texas",
        "country": "USA",
        "draft_year": 2007,
        "draft_round": 1,
        "draft_number": 2,
        "team_id": 11
      },
      "team": {
        "id": 24,
        "conference": "West",
        "division": "Pacific",
        "city": "Phoenix",
        "name": "Suns",
        "full_name": "Phoenix Suns",
        "abbreviation": "PHX"
      }
    },
    ...
  ],
  "meta": {
    "per_page": 25
  }
}

This endpoint retrieves contracts for a specific player, optionally filtered by seasons. Results are ordered by season in descending order. This endpoint supports pagination.

HTTP Request

GET https://api.balldontlie.io/v1/contracts/players

Query Parameters

Parameter	Required	Description
player_id	true	The player ID
seasons	false	Filter by specific seasons. This should be an array: `?seasons[]=2024&seasons[]=2025`
cursor	false	The cursor, used for pagination
per_page	false	The number of results per page. Defaults to 25. Max is 100

Get Player Contract Aggregates

curl "https://api.balldontlie.io/v1/contracts/players/aggregate?player_id=140" \
  -H "Authorization: YOUR_API_KEY"

const axios = require("axios");

const response = await axios.get(
  "https://api.balldontlie.io/v1/contracts/players/aggregate",
  {
    params: {
      player_id: 140,
    },
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);

console.log(response.data);

import requests

response = requests.get(
    'https://api.balldontlie.io/v1/contracts/players/aggregate',
    params={'player_id': 140},
    headers={'Authorization': 'YOUR_API_KEY'}
)

print(response.json())

{
  "data": [
    {
      "id": 4231,
      "player_id": 140,
      "start_year": 2026,
      "end_year": 2027,
      "contract_type": "Veteran Extension",
      "contract_status": "UPCOMING EXTENSION",
      "contract_years": 2,
      "total_value": 90000000,
      "average_salary": 45000000,
      "guaranteed_at_signing": 90000000,
      "total_guaranteed": 90000000,
      "signed_using": null,
      "free_agent_year": 2028,
      "free_agent_status": "UFA",
      "contract_notes": ["2027-28: Player Option (deadline 6/29/27)"],
      "team_id": 11,
      "player": {
        "id": 140,
        "first_name": "Kevin",
        "last_name": "Durant",
        "position": "F",
        "height": "6-11",
        "weight": "240",
        "jersey_number": "7",
        "college": "Texas",
        "country": "USA",
        "draft_year": 2007,
        "draft_round": 1,
        "draft_number": 2,
        "team_id": 11
      },
      "team": {
        "id": 11,
        "conference": "West",
        "division": "Southwest",
        "city": "Houston",
        "name": "Rockets",
        "full_name": "Houston Rockets",
        "abbreviation": "HOU"
      }
    },
    {
      "id": 4238,
      "player_id": 140,
      "start_year": 2007,
      "end_year": 2010,
      "contract_type": "Rookie",
      "contract_status": "expired",
      "contract_years": 4,
      "total_value": 19505783,
      "average_salary": 4876446,
      "guaranteed_at_signing": null,
      "total_guaranteed": 19505783,
      "signed_using": "rookie-scale-exception",
      "free_agent_year": null,
      "free_agent_status": null,
      "contract_notes": null,
      "team_id": null,
      "player": {
        "id": 140,
        "first_name": "Kevin",
        "last_name": "Durant",
        "position": "F",
        "height": "6-11",
        "weight": "240",
        "jersey_number": "7",
        "college": "Texas",
        "country": "USA",
        "draft_year": 2007,
        "draft_round": 1,
        "draft_number": 2,
        "team_id": 11
      },
      "team": null
    },
    ...
  ]
}

This endpoint retrieves aggregated multi-year contract data for a specific player, including total contract value, guaranteed amounts, free agency information, and contract metadata. Results are ordered by start_year in descending order.

HTTP Request

GET https://api.balldontlie.io/v1/contracts/players/aggregate

Query Parameters

Parameter	Required	Description
player_id	true	The player ID