MLB API
Welcome to the BALLDONTLIE MLB API, the best MLB API on the planet. This API contains data from 2002-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.
If you're looking for the NBA API go here.
If you're looking for the NFL API go here.
Join us on discord.
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 MLB will not be applied to the sports.
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 |
| Player Injuries | No | Yes | Yes |
| Active Players | No | Yes | Yes |
| Team Standings | No | Yes | Yes |
| Player Stats | No | Yes | Yes |
| Player Season Stats | No | No | Yes |
| Team Season Stats | No | No | Yes |
The feature breakdown per tier is shown in the table below.
| Tier | Requests / Min | $USD / mo. |
|---|---|---|
| GOAT | 6000 | 39.99 |
| ALL-STAR | 600 | 9.99 |
| Free | 30 | 0 |
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"
Make sure to replace
YOUR_API_KEYwith 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
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/mlb/v1/teams" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": [
{
"id": 6,
"slug": "chicago-white-sox",
"abbreviation": "CHW",
"display_name": "Chicago White Sox",
"short_display_name": "White Sox",
"name": "White Sox",
"location": "Chicago",
"league": "American",
"division": "Central"
},
...
]
}
This endpoint retrieves all teams.
HTTP Request
GET https://api.balldontlie.io//mlb/v1/teams
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| division | false | Returns teams that belong to this division |
| league | false | Returns teams that belong to this league |
Get a Specific Team
curl "https://api.balldontlie.io/mlb/v1/teams/<ID>" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": {
"id": 6,
"slug": "chicago-white-sox",
"abbreviation": "CHW",
"display_name": "Chicago White Sox",
"short_display_name": "White Sox",
"name": "White Sox",
"location": "Chicago",
"league": "American",
"division": "Central"
}
}
This endpoint retrieves a specific team.
HTTP Request
GET https://api.balldontlie.io/mlb/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/mlb/v1/players" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": [
{
"id": 208,
"first_name": "Shohei",
"last_name": "Ohtani",
"full_name": "Shohei Ohtani",
"debut_year": 2018,
"jersey": "17",
"college": null,
"position": "Designated Hitter",
"active": true,
"birth_place": "Oshu, Japan",
"dob": "5/7/1994",
"age": 30,
"height": "6' 4\"",
"weight": "210 lbs",
"draft": null,
"bats_throws": "Left/Right",
"team": {
"id": 14,
"slug": "los-angeles-dodgers",
"abbreviation": "LAD",
"display_name": "Los Angeles Dodgers",
"short_display_name": "Dodgers",
"name": "Dodgers",
"location": "Los Angeles",
"league": "National",
"division": "West"
}
},
...
],
"meta": { "next_cursor": 25, "per_page": 25 }
}
This endpoint retrieves all players.
HTTP Request
GET https://api.balldontlie.io/mlb/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=shohei will return players that have 'shohei' in their first or last name. |
| first_name | false | Returns players whose first name matches this value. For example, ?search=shohei will return players that have 'shohei' in their first name. |
| last_name | false | Returns players whose last name matches this value. For example, ?search=ohtani will return players that have 'ohtani' 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/mlb/v1/players/<ID>" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": {
"id": 208,
"first_name": "Shohei",
"last_name": "Ohtani",
"full_name": "Shohei Ohtani",
"debut_year": 2018,
"jersey": "17",
"college": null,
"position": "Designated Hitter",
"active": true,
"birth_place": "Oshu, Japan",
"dob": "5/7/1994",
"age": 30,
"height": "6' 4\"",
"weight": "210 lbs",
"draft": null,
"bats_throws": "Left/Right",
"team": {
"id": 14,
"slug": "los-angeles-dodgers",
"abbreviation": "LAD",
"display_name": "Los Angeles Dodgers",
"short_display_name": "Dodgers",
"name": "Dodgers",
"location": "Los Angeles",
"league": "National",
"division": "West"
}
}
}
This endpoint retrieves a specific player.
HTTP Request
GET https://api.balldontlie.io/mlb/v1/players/<ID>
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| ID | true | The ID of the player to retrieve |
Player Injuries
Get All Player Injuries
curl "https://api.balldontlie.io/mlb/v1/player_injuries" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": [
{
"player": {
"id": 208,
"first_name": "Shohei",
"last_name": "Ohtani",
"full_name": "Shohei Ohtani",
"debut_year": 2018,
"jersey": "17",
"college": null,
"position": "Designated Hitter",
"active": true,
"birth_place": "Oshu, Japan",
"dob": "5/7/1994",
"age": 30,
"height": "6' 4\"",
"weight": "210 lbs",
"draft": null,
"bats_throws": "Left/Right",
"team": {
"id": 14,
"slug": "los-angeles-dodgers",
"abbreviation": "LAD",
"display_name": "Los Angeles Dodgers",
"short_display_name": "Dodgers",
"name": "Dodgers",
"location": "Los Angeles",
"league": "National",
"division": "West"
}
},
"date": "2024-11-05T23:32:00.000Z",
"return_date": "2025-02-01T00:00:00.000Z",
"type": "Shoulder",
"detail": "Surgery",
"side": "Left",
"status": "Out",
"long_comment": "Ohtani was forced to depart Game 2 of the World Series on Saturday due to a left shoulder subluxation suffered on a slide into second base. However, an MRI confirmed that he doesn't have any structural damage and he was able to go through 80 percent of his daily routine Sunday without issue. Ohtani will not be allowed to attempt any stolen bases Monday and perhaps not for the remainder of the series, per Alden Gonzalez of ESPN.com, but he's feeling well enough to give it a go at the plate as the Dodgers try to take a commanding 3-0 series lead.",
"short_comment": "Ohtani (shoulder) will start at designated hitter and bat leadoff Monday in Game 3 of the World Series versus the Yankees, Bill Plunkett of The Orange County Register reports."
},
...
],
"meta": { "next_cursor": 62089, "per_page": 25 }
}
This endpoint retrieves all player injuries.
HTTP Request
GET https://api.balldontlie.io/mlb/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 |
Active Players
Get All Active Players
curl "https://api.balldontlie.io/mlb/v1/players/active" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"first_name": "Ryan",
"last_name": "Thompson",
"full_name": "Ryan Thompson",
"debut_year": 2020,
"jersey": "81",
"college": null,
"position": "Relief Pitcher",
"active": true,
"birth_place": "Turner, OR",
"dob": "26/6/1992",
"age": 32,
"height": "6' 5\"",
"weight": "210 lbs",
"draft": "2014: Rd 23, Pk 676 (HOU)",
"bats_throws": "Right/Right",
"team": {
"id": 1,
"slug": "arizona-diamondbacks",
"abbreviation": "ARI",
"display_name": "Arizona Diamondbacks",
"short_display_name": "Diamondbacks",
"name": "Diamondbacks",
"location": "Arizona",
"league": "National",
"division": "West"
}
},
...
],
"meta": { "next_cursor": 23, "per_page": 25 }
}
This endpoint retrieves all active players.
HTTP Request
GET https://api.balldontlie.io/mlb/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=shohei will return players that have 'shohei' in their first or last name. |
| first_name | false | Returns players whose first name matches this value. For example, ?search=shohei will return players that have 'shohei' in their first name. |
| last_name | false | Returns players whose last name matches this value. For example, ?search=ohtani will return players that have 'ohtani' 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 |
Games
Get All Games
curl "https://api.balldontlie.io/mlb/v1/games" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": [
{
"id": 58590,
"home_team_name": "New York Yankees",
"away_team_name": "Los Angeles Dodgers",
"home_team": {
"id": 19,
"slug": "new-york-yankees",
"abbreviation": "NYY",
"display_name": "New York Yankees",
"short_display_name": "Yankees",
"name": "Yankees",
"location": "New York",
"league": "American",
"division": "East"
},
"away_team": {
"id": 14,
"slug": "los-angeles-dodgers",
"abbreviation": "LAD",
"display_name": "Los Angeles Dodgers",
"short_display_name": "Dodgers",
"name": "Dodgers",
"location": "Los Angeles",
"league": "National",
"division": "West"
},
"season": 2024,
"postseason": true,
"date": "2024-10-30T00:08:00.000Z",
"home_team_data": {
"hits": 9,
"runs": 11,
"errors": 0,
"inning_scores": [0, 1, 4, 0, 0, 1, 0, 5]
},
"away_team_data": {
"hits": 6,
"runs": 4,
"errors": 1,
"inning_scores": [2, 0, 0, 0, 2, 0, 0, 0, 0]
},
"venue": "Yankee Stadium",
"attendance": 49354,
"conference_play": false,
"status": "STATUS_FINAL",
"period": 9,
"clock": 0,
"display_clock": "0:00",
"scoring_summary": [
{
"play": "Freeman homered to right (343 feet), Betts scored.",
"inning": "top",
"period": "1st",
"away_score": 2,
"home_score": 0
},
{
"play": "Verdugo grounded out to first, Volpe scored, Wells to third.",
"inning": "bottom",
"period": "2nd",
"away_score": 2,
"home_score": 1
},
{
"play": "Volpe homered to left center (390 feet), Judge scored, Chisholm Jr. scored and Stanton scored.",
"inning": "bottom",
"period": "3rd",
"away_score": 2,
"home_score": 5
},
{
"play": "Smith homered to right center (364 feet).",
"inning": "top",
"period": "5th",
"away_score": 3,
"home_score": 5
},
{
"play": "Freeman grounded into fielder's choice to second, Edman scored, Betts out at second.",
"inning": "top",
"period": "5th",
"away_score": 4,
"home_score": 5
},
{
"play": "Wells homered to right (384 feet).",
"inning": "bottom",
"period": "6th",
"away_score": 4,
"home_score": 6
},
{
"play": "Verdugo grounded into fielder's choice to second, Volpe scored, Wells third.",
"inning": "bottom",
"period": "8th",
"away_score": 4,
"home_score": 7
},
{
"play": "Torres homered to right center (366 feet), Wells scored and Verdugo scored.",
"inning": "bottom",
"period": "8th",
"away_score": 4,
"home_score": 10
},
{
"play": "Judge singled to left, Soto scored.",
"inning": "bottom",
"period": "8th",
"away_score": 4,
"home_score": 11
}
]
},
...
],
"meta": {
"per_page": 25,
"next_cursor": 7024
}
}
This endpoint retrieves all games.
HTTP Request
GET https://api.balldontlie.io/mlb/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 |
Get a Specific Game
curl "https://api.balldontlie.io/mlb/v1/games/<ID>" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": {
"id": 58590,
"home_team_name": "New York Yankees",
"away_team_name": "Los Angeles Dodgers",
"home_team": {
"id": 19,
"slug": "new-york-yankees",
"abbreviation": "NYY",
"display_name": "New York Yankees",
"short_display_name": "Yankees",
"name": "Yankees",
"location": "New York",
"league": "American",
"division": "East"
},
"away_team": {
"id": 14,
"slug": "los-angeles-dodgers",
"abbreviation": "LAD",
"display_name": "Los Angeles Dodgers",
"short_display_name": "Dodgers",
"name": "Dodgers",
"location": "Los Angeles",
"league": "National",
"division": "West"
},
"season": 2024,
"postseason": true,
"date": "2024-10-30T00:08:00.000Z",
"home_team_data": {
"hits": 9,
"runs": 11,
"errors": 0,
"inning_scores": [0, 1, 4, 0, 0, 1, 0, 5]
},
"away_team_data": {
"hits": 6,
"runs": 4,
"errors": 1,
"inning_scores": [2, 0, 0, 0, 2, 0, 0, 0, 0]
},
"venue": "Yankee Stadium",
"attendance": 49354,
"conference_play": false,
"status": "STATUS_FINAL",
"period": 9,
"clock": 0,
"display_clock": "0:00",
"scoring_summary": [
{
"play": "Freeman homered to right (343 feet), Betts scored.",
"inning": "top",
"period": "1st",
"away_score": 2,
"home_score": 0
},
{
"play": "Verdugo grounded out to first, Volpe scored, Wells to third.",
"inning": "bottom",
"period": "2nd",
"away_score": 2,
"home_score": 1
},
{
"play": "Volpe homered to left center (390 feet), Judge scored, Chisholm Jr. scored and Stanton scored.",
"inning": "bottom",
"period": "3rd",
"away_score": 2,
"home_score": 5
},
{
"play": "Smith homered to right center (364 feet).",
"inning": "top",
"period": "5th",
"away_score": 3,
"home_score": 5
},
{
"play": "Freeman grounded into fielder's choice to second, Edman scored, Betts out at second.",
"inning": "top",
"period": "5th",
"away_score": 4,
"home_score": 5
},
{
"play": "Wells homered to right (384 feet).",
"inning": "bottom",
"period": "6th",
"away_score": 4,
"home_score": 6
},
{
"play": "Verdugo grounded into fielder's choice to second, Volpe scored, Wells third.",
"inning": "bottom",
"period": "8th",
"away_score": 4,
"home_score": 7
},
{
"play": "Torres homered to right center (366 feet), Wells scored and Verdugo scored.",
"inning": "bottom",
"period": "8th",
"away_score": 4,
"home_score": 10
},
{
"play": "Judge singled to left, Soto scored.",
"inning": "bottom",
"period": "8th",
"away_score": 4,
"home_score": 11
}
]
}
}
This endpoint retrieves a specific game.
HTTP Request
GET https://api.balldontlie.io/mlb/v1/games/<ID>
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| ID | true | The ID of the game to retrieve |
Stats
Get All Stats
curl "https://api.balldontlie.io/mlb/v1/stats"
The above command returns JSON structured like this:
{
"data": [
{
"player": {
"id": 208,
"first_name": "Shohei",
"last_name": "Ohtani",
"full_name": "Shohei Ohtani",
"debut_year": 2018,
"jersey": "17",
"college": null,
"position": "Designated Hitter",
"active": true,
"birth_place": "Oshu, Japan",
"dob": "5/7/1994",
"age": 30,
"height": "6' 4\"",
"weight": "210 lbs",
"draft": null,
"bats_throws": "Left/Right"
},
"game": {
"id": 58595,
"home_team_name": "New York Yankees",
"away_team_name": "Los Angeles Dodgers",
"home_team": {
"id": 19,
"slug": "new-york-yankees",
"abbreviation": "NYY",
"display_name": "New York Yankees",
"short_display_name": "Yankees",
"name": "Yankees",
"location": "New York",
"league": "American",
"division": "East"
},
"away_team": {
"id": 14,
"slug": "los-angeles-dodgers",
"abbreviation": "LAD",
"display_name": "Los Angeles Dodgers",
"short_display_name": "Dodgers",
"name": "Dodgers",
"location": "Los Angeles",
"league": "National",
"division": "West"
},
"season": 2024,
"postseason": true,
"date": "2024-10-31T00:08:00.000Z",
"home_team_data": {
"hits": 8,
"runs": 6,
"errors": 3,
"inning_scores": [3, 1, 1, 0, 0, 1, 0, 0, 0]
},
"away_team_data": {
"hits": 7,
"runs": 7,
"errors": 0,
"inning_scores": [0, 0, 0, 0, 5, 0, 0, 2, 0]
},
"venue": "Yankee Stadium",
"attendance": 49263,
"conference_play": false,
"status": "STATUS_FINAL",
"period": 9,
"clock": 0,
"display_clock": "0:00",
"scoring_summary": [
{
"play": "Judge homered to right center (403 feet), Soto scored.",
"inning": "bottom",
"period": "1st",
"away_score": 0,
"home_score": 2
},
{
"play": "Chisholm Jr. homered to right center (392 feet).",
"inning": "bottom",
"period": "1st",
"away_score": 0,
"home_score": 3
},
{
"play": "Verdugo singled to right, Volpe scored.",
"inning": "bottom",
"period": "2nd",
"away_score": 0,
"home_score": 4
},
{
"play": "Stanton homered to right (385 feet).",
"inning": "bottom",
"period": "3rd",
"away_score": 0,
"home_score": 5
},
{
"play": "Betts reached on infield single to first, E. Hernández scored, Smith to second, Edman to third.",
"inning": "top",
"period": "5th",
"away_score": 1,
"home_score": 5
},
{
"play": "Freeman singled to center, Edman scored and Smith scored, Betts to third.",
"inning": "top",
"period": "5th",
"away_score": 3,
"home_score": 5
},
{
"play": "T. Hernández doubled to center, Betts scored and Freeman scored.",
"inning": "top",
"period": "5th",
"away_score": 5,
"home_score": 5
},
{
"play": "Stanton hit sacrifice fly to center, Soto scored, Chisholm Jr. to second.",
"inning": "bottom",
"period": "6th",
"away_score": 5,
"home_score": 6
},
{
"play": "Lux hit sacrifice fly to center, E. Hernández scored, Edman to third.",
"inning": "top",
"period": "8th",
"away_score": 6,
"home_score": 6
},
{
"play": "Betts hit sacrifice fly to center, Edman scored, Smith to third.",
"inning": "top",
"period": "8th",
"away_score": 7,
"home_score": 6
}
]
},
"team_name": "Los Angeles Dodgers",
"at_bats": 4,
"runs": 0,
"hits": 0,
"rbi": 0,
"hr": 0,
"bb": 0,
"k": 1,
"avg": 0.23,
"obp": 0.373,
"slg": 0.393,
"ip": null,
"p_hits": null,
"p_runs": null,
"er": null,
"p_bb": null,
"p_k": null,
"p_hr": null,
"pitch_count": null,
"strikes": null,
"era": null
},
...
],
"meta": { "per_page": 25 }
}
This endpoint retrieves all stats.
HTTP Request
GET https://api.balldontlie.io/mlb/v1/stats
Query Parameters
| 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 |
| seasons | false | Returns stats that occurred in these seasons. This should be an array: ?seasons[]=2022&seasons[]=2023 |
Season Stats
Get Season Stats
curl "https://api.balldontlie.io/mlb/v1/season_stats"
The above command returns JSON structured like this:
{
"data": [
{
"player": {
"id": 1106,
"first_name": "Juan",
"last_name": "Soto",
"full_name": "Juan Soto",
"debut_year": 2018,
"jersey": "22",
"college": null,
"position": "Left Fielder",
"active": false,
"birth_place": "Santo Domingo, Dominican Republic",
"dob": "25/10/1998",
"age": 26,
"height": "6' 2\"",
"weight": "224 lbs",
"draft": null,
"bats_throws": "Left/Left",
"team": {
"id": 19,
"slug": "new-york-yankees",
"abbreviation": "NYY",
"display_name": "New York Yankees",
"short_display_name": "Yankees",
"name": "Yankees",
"location": "New York",
"league": "American",
"division": "East"
}
},
"team_name": "Yankees",
"season": 2024,
"postseason": false,
"batting_gp": 157,
"batting_ab": 576,
"batting_r": 128,
"batting_h": 166,
"batting_avg": 0.2881944,
"batting_2b": 31,
"batting_3b": 4,
"batting_hr": 41,
"batting_rbi": 109,
"batting_tb": 328,
"batting_bb": 129,
"batting_so": 119,
"batting_sb": 7,
"batting_obp": 0.4193548,
"batting_slg": 0.5694444,
"batting_ops": 0.9887992,
"batting_war": 7.92,
"pitching_gp": null,
"pitching_gs": null,
"pitching_qs": null,
"pitching_w": null,
"pitching_l": null,
"pitching_era": null,
"pitching_sv": null,
"pitching_hld": null,
"pitching_ip": null,
"pitching_h": null,
"pitching_er": null,
"pitching_hr": null,
"pitching_bb": null,
"pitching_whip": null,
"pitching_k": null,
"pitching_k_per_9": null,
"pitching_war": null,
"fielding_gp": 157,
"fielding_gs": 0,
"fielding_fip": 0,
"fielding_tc": 314,
"fielding_po": 302,
"fielding_a": 10,
"fielding_fp": 0.9936306,
"fielding_e": 2,
"fielding_dp": 0,
"fielding_rf": 0,
"fielding_dwar": -0.53,
"fielding_pb": 0,
"fielding_cs": 0,
"fielding_cs_percent": 0,
"fielding_sba": 0
},
...
],
"meta": { "next_cursor": 83571, "per_page": 25 }
}
HTTP Request
GET https://api.balldontlie.io/mlb/v1/season_stats
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| season | true | Returns season stats for this season |
| player_ids | false | Returns season stats for these players. This should be an array: player_ids[]=1 |
| team_id | false | Returns season stats for this team |
| postseason | false | Returns season stats for postseason or regular season. Defaults to false. |
| sort_by | false | Returns season stats sorted by this attribute. Most attributes in the response body can be specified |
| sort_order | false | Returns season stats sorted in asc or desc |
Team Standings
Get Team Standings
curl "https://api.balldontlie.io/mlb/v1/standings?season=2024" \
-H "Authorization: YOUR_API_KEY"
The above command returns JSON structured like this:
{
"data": [
{
"team": {
"id": 19,
"slug": "new-york-yankees",
"abbreviation": "NYY",
"display_name": "New York Yankees",
"short_display_name": "Yankees",
"name": "Yankees",
"location": "New York",
"league": "American",
"division": "East"
},
"league_name": "American League",
"league_short_name": "AL",
"division_name": "American League East",
"division_short_name": "AL East",
"team_name": "New York Yankees",
"ot_losses": 8,
"ot_wins": 8,
"avg_points_against": 4.123457,
"avg_points_for": 5.0308642,
"clincher": "*",
"differential": 0.9000000000000004,
"division_win_percent": 0.5,
"games_behind": 0,
"games_played": 162,
"league_win_percent": 0.61206895,
"losses": 68,
"playoff_seed": 1,
"point_differential": 147,
"game_back_points": 13,
"points_against": 668,
"points_for": 815,
"streak": 1,
"ties": 0,
"win_percent": 0.5802469,
"wins": 94,
"division_games_behind": 0,
"division_percent": 100,
"division_tied": 0,
"home_losses": 37,
"home_ties": 0,
"home_wins": 44,
"magic_number_division": -2,
"magic_number_wildcard": -7,
"playoff_percent": 100,
"road_losses": 31,
"road_ties": 0,
"road_wins": 50,
"wildcard_percent": 0,
"total": "94-68",
"home": "44-37",
"road": "50-31",
"intra_division": "26-26",
"intra_league": "71-45",
"last_ten_games": "5-5",
"season": 2024
},
...
]
}
This endpoint retrieves regular season team standings.
HTTP Request
GET https://api.balldontlie.io/mlb/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. |
Team Season Stats
Get Team Season Stats
curl "https://api.balldontlie.io/mlb/v1/teams/season_stats"
The above command returns JSON structured like this:
{
"data": [
{
"team": {
"id": 23,
"slug": "san-diego-padres",
"abbreviation": "SD",
"display_name": "San Diego Padres",
"short_display_name": "Padres",
"name": "Padres",
"location": "San Diego",
"league": "National",
"division": "West"
},
"team_name": "San Diego Padres",
"postseason": false,
"season": 2024,
"gp": 162,
"batting_ab": 5526,
"batting_r": 760,
"batting_h": 1456,
"batting_2b": 259,
"batting_3b": 18,
"batting_hr": 190,
"batting_rbi": 726,
"batting_tb": 2321,
"batting_bb": 458,
"batting_so": 1077,
"batting_sb": 120,
"batting_avg": 0.26348174,
"batting_obp": 0.3244935,
"batting_slg": 0.42001447,
"batting_ops": 0.74450797,
"pitching_w": 93,
"pitching_l": 69,
"pitching_era": 3.858036,
"pitching_sv": 44,
"pitching_cg": 1,
"pitching_sho": 16,
"pitching_qs": 65,
"pitching_ip": 1439.1,
"pitching_h": 1296,
"pitching_er": 617,
"pitching_hr": 169,
"pitching_bb": 462,
"pitching_k": 1453,
"pitching_oba": 0.23845446,
"pitching_whip": 1.2213987,
"fielding_e": 75,
"fielding_fp": 0.98681897,
"fielding_tc": 5690,
"fielding_po": 4318,
"fielding_a": 1297
},
...
],
"meta": { "next_cursor": 83571, "per_page": 25 }
}
HTTP Request
GET https://api.balldontlie.io/mlb/v1/teams/season_stats
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| season | true | Returns season stats for this season |
| team_id | false | Returns season stats for this team |
| postseason | false | Returns season stats for postseason or regular season. Defaults to false. |