# MLB > Read Major League Baseball's official Stats API, the same data that powers MLB.com and Gameday. Get schedules and live scores, a game's boxscore, linescore and pitch-by-pitch play-by-play, the standings, team and player stats in any split, leaderboards, rosters and biographies, transactions, the draft, awards, milestones, attendance and pace of play. Covers the minor leagues, winter, college, international and Negro League Baseball as well as MLB itself. No account or API key required. App · Sports · 71 actions. Web page: https://docs.lodol.com/docs/integrations/mlb ## Actions ### Compare team stats Get a table of statistics across teams, ranked by whichever one you choose: the league table of team batting, pitching or fielding. **Inputs** - Stat groups (`group`, list, required): Which kinds of statistics to return. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. Default: `["hitting"]`. - Stat splits (`stats`, list): How to slice the statistics. Leave blank for season totals. One or more of: `season`, `career`, `yearByYear` (Year by year), `gameLog` (Game log), `statSplits` (Stat splits), `advanced`, `standard`, `projected`, `projectedRos` (Projected rest of season), `yearByYearAdvanced` (Year by year advanced), and 51 more. - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - Leagues (`league_ids`, list): Only return results for these leagues. Leave blank for all leagues. - Game type (`game_type`, text): Only count games of this type. Leave blank to include every type. One of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Sort by (`sort_stat`, text): Which statistic to sort the rows by. One of: `homeRuns` (Home runs), `battingAverage` (Batting average), `runsBattedIn` (Runs batted in), `hits`, `runs`, `stolenBases` (Stolen bases), `onBasePercentage` (On base percentage), `sluggingPercentage` (Slugging percentage), `onBasePlusSlugging` (On base plus slugging), `earnedRunAverage` (Earned run average), and 60 more. - Sort direction (`order`, text): Whether to list the highest or the lowest values first. One of: `desc` (Highest first), `asc` (Lowest first). - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Last N days (`days_back`, number): Only count the last this many days of games, ending yesterday. From 1 to 365. - Number of results (`limit`, number): How many rows to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`. - Rows to skip (`offset`, number): How many rows to skip before returning results. Use it with the number of results to page through a long list (0, then 50, then 100, ...). From 0 to 1000000. Default: `0`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "stats": [ { "group": { "displayName": "hitting" }, "splits": [ { "gameType": "R", "league": { "id": 104, "name": "National League" }, "player": { "fullName": "Shohei Ohtani", "id": 660271 }, "season": "2024", "sport": { "abbreviation": "MLB", "id": 1 }, "stat": { "atBats": 636, "avg": ".310", "doubles": 38, "gamesPlayed": 159, "hits": 197, "homeRuns": 54, "obp": ".390", "ops": "1.036", "rbi": 130, "runs": 134, "slg": ".646", "stolenBases": 59, "triples": 7 }, "team": { "id": 119, "name": "Los Angeles Dodgers" } } ], "totalSplits": 1, "type": { "displayName": "season" } } ] } ``` ### Get a game with Statcast metrics Get a game's full feed with the Statcast measurements attached to each play: pitch velocity and spin, exit velocity, launch angle and hit distance. Another large response, so trim it with "Fields to keep". **Inputs** - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. - Point in the game (`timecode`, text): Optional: return the game as it stood at this moment rather than now. List game timestamps returns the values this accepts. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "gameData": { "game": { "pk": 776501, "type": "R" } }, "gamePk": 776501, "liveData": { "plays": { "allPlays": [ { "playEvents": [ { "hitData": { "launchAngle": 27, "launchSpeed": 104.2, "totalDistance": 402 }, "pitchData": { "breaks": { "spinRate": 2412 }, "startSpeed": 98.4 }, "playId": "b0948e04-9bd4-39dd-93b2-4a00ae272798" } ] } ] } } } ``` ### Get a game's boxscore Get a game's boxscore: each team's batting and pitching lines, the batting order, substitutions, the umpires and the team totals. **Inputs** - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. - Point in the game (`timecode`, text): Optional: return the game as it stood at this moment rather than now. List game timestamps returns the values this accepts. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "officials": [ { "official": { "fullName": "Lance Barksdale", "id": 427146 }, "officialType": "Home Plate" } ], "teams": { "away": { "batters": [ 624413, 596019 ], "team": { "id": 121, "name": "New York Mets" }, "teamStats": { "batting": { "hits": 9, "homeRuns": 1, "runs": 4 } } }, "home": { "batters": [ 670032, 663656 ], "team": { "id": 116, "name": "Detroit Tigers" }, "teamStats": { "batting": { "hits": 6, "homeRuns": 0, "runs": 2 } } } } } ``` ### Get a game's context metrics Get the situational context of a game as it stands: the leverage of the moment, each side's chance of winning, and the game's current state. **Inputs** - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. - Point in the game (`timecode`, text): Optional: return the game as it stood at this moment rather than now. List game timestamps returns the values this accepts. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "awayWinProbability": 91.4, "centerFieldSacFlyProbability": {}, "game": { "gameDate": "2025-09-01T17:10:00Z", "gameGuid": "d1b0a9c4-3d5f-4a2b-9a41-2f2b7d4c1a55", "gamePk": 776501, "gameType": "R", "link": "/api/v1/game/776501/feed/live", "officialDate": "2025-09-01", "season": "2025", "status": { "abstractGameState": "Final", "codedGameState": "F", "detailedState": "Final", "statusCode": "F" }, "teams": { "away": { "isWinner": true, "score": 4, "team": { "id": 121, "name": "New York Mets" } }, "home": { "isWinner": false, "score": 2, "team": { "id": 116, "name": "Detroit Tigers" } } }, "venue": { "id": 2394, "name": "Comerica Park" } }, "homeWinProbability": 8.6, "leftFieldSacFlyProbability": {}, "rightFieldSacFlyProbability": {} } ``` ### Get a game's feed updates Get only what changed in a game's live feed since a moment you already have, instead of downloading the whole feed again. Poll a game in progress with this: take the timestamp from your last feed, pass it as the start, and apply the patch you get back. **Inputs** - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. - Changed since (`start_timecode`, text): Return everything that changed after this moment. Use the timestamp from your previous feed response. - Changed up to (`end_timecode`, text): Stop at this moment instead of the latest state. **Outputs**: None. **Example output** ```json { "gameData": { "game": { "pk": 776501, "type": "R" } }, "gamePk": 776501, "link": "/api/v1.1/game/776501/feed/live", "liveData": { "plays": { "currentPlay": { "about": { "atBatIndex": 74 } } } }, "metaData": { "timeStamp": "20250901_201500" } } ``` ### Get a game's linescore Get a game's linescore: runs, hits and errors by inning, the current inning and count while a game is live, and who is due up next. **Inputs** - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. - Point in the game (`timecode`, text): Optional: return the game as it stood at this moment rather than now. List game timestamps returns the values this accepts. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "currentInning": 9, "inningState": "Bottom", "innings": [ { "away": { "errors": 0, "hits": 2, "runs": 2 }, "home": { "errors": 0, "hits": 1, "runs": 0 }, "num": 1 } ], "scheduledInnings": 9, "teams": { "away": { "errors": 0, "hits": 9, "runs": 4 }, "home": { "errors": 1, "hits": 6, "runs": 2 } } } ``` ### Get a game's live feed Get everything MLB holds about one game in a single payload (the GUMBO feed): both rosters, the current state, every play and pitch, and the boxscore. This is the feed that powers Gameday and it updates while the game is in progress. It is a large response, so use "Fields to keep" to trim it to the parts your workflow needs. **Inputs** - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. - Point in the game (`timecode`, text): Optional: return the game as it stood at this moment rather than now. List game timestamps returns the values this accepts. - Include the play at that moment (`inclusive_timecode`, true/false): On, plays at or before the chosen moment are included. Off, only those strictly before it. Default: `false`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "gameData": { "game": { "pk": 776501, "season": "2025", "type": "R" } }, "gamePk": 776501, "liveData": { "linescore": { "currentInning": 9, "isTopInning": false }, "plays": { "currentPlay": { "result": { "description": "Strikeout." } } } }, "metaData": { "gameEvents": [ "strikeout" ], "timeStamp": "20250901_201500" } } ``` ### Get a game's media and recaps Get the editorial content MLB published for a game: the written recap, the highlight videos with their playback URLs, and the photos. **Inputs** - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "editorial": { "recap": { "mlb": { "headline": "Mets hold on to beat Tigers", "seoTitle": "Mets 4, Tigers 2" } } }, "highlights": { "highlights": { "items": [ { "duration": "00:00:31", "playbacks": [ { "name": "mp4Avc", "url": "https://mlb-cuts-diamond.mlb.com/example.mp4" } ], "title": "D\u00edaz seals it" } ] } }, "link": "/api/v1/game/776501/content" } ``` ### Get a game's play-by-play Get every play of a game in order, each with its batter and pitcher, the pitches thrown, the count, the runners and the outcome. Each pitch carries a play id, which is what the video and tracking data are keyed by. **Inputs** - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. - Point in the game (`timecode`, text): Optional: return the game as it stood at this moment rather than now. List game timestamps returns the values this accepts. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "allPlays": [ { "about": { "atBatIndex": 74, "inning": 9, "isTopInning": false }, "matchup": { "batter": { "fullName": "Riley Greene", "id": 682985 }, "pitcher": { "fullName": "Edwin D\u00edaz", "id": 605280 } }, "result": { "awayScore": 4, "description": "Riley Greene strikes out swinging.", "event": "Strikeout", "homeScore": 2, "rbi": 0, "type": "atBat" } } ], "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "currentPlay": { "about": { "atBatIndex": 74 } } } ``` ### Get a game's win probability Get how each team's chance of winning moved play by play, so a workflow can find the swing that decided a game. **Inputs** - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. - Point in the game (`timecode`, text): Optional: return the game as it stood at this moment rather than now. List game timestamps returns the values this accepts. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs** - `winProbability` (list) **Example output** ```json { "winProbability": [ { "about": { "atBatIndex": 41, "inning": 6 }, "awayTeamWinProbability": 37.9, "homeTeamWinProbability": 62.1, "homeTeamWinProbabilityAdded": 18.4, "leverageIndex": 2.3, "result": { "description": "Home run.", "event": "Home Run" } } ] } ``` ### Get a Home Run Derby Get a Home Run Derby round by round, or just its bracket or its player pool. The derby's id is the All-Star Weekend event id: get the schedule for All-Star week with the "All events" type to find it. **Inputs** - Derby ID (`game_pk`, text, required): The derby's event id. Get the schedule for All-Star week with the "All events" type to find it. - Section (`section`, text): Which part of the derby to read. Defaults to the whole thing. One of: `full` (Full derby (rounds and matchups)), `bracket` (Bracket only), `pool` (Player pool only). Default: `full`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "info": { "eventDate": "2025-07-15T00:00:00Z", "id": 788030, "name": "2025 MLB All-Star Workout Day: Home Run Derby", "venue": { "id": 4705, "name": "Truist Park" } }, "players": [ { "fullName": "Cal Raleigh", "id": 663728 } ], "rounds": [ { "matchups": [ { "bottomSeed": { "complete": true, "player": { "fullName": "Brent Rooker", "id": 667670 }, "topDerbyHitData": { "launchSpeed": 110.0, "totalDistance": 461.0 }, "winner": false }, "topSeed": { "complete": true, "player": { "fullName": "Cal Raleigh", "id": 663728 }, "topDerbyHitData": { "launchSpeed": 112.0, "totalDistance": 471.0 }, "winner": true } } ], "round": 1 } ], "status": { "clockStopped": true, "currentRound": 3, "state": "Final" } } ``` ### Get a league Get one league's record, including its season dates and its rules on the designated hitter and the wild card. **Inputs** - League (`league_id`, text, required): Which league to read. - Season (`season`, text): Which season to read. Defaults to the current season. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "leagues": [ { "abbreviation": "AL", "id": 103, "name": "American League", "seasonDateInfo": { "regularSeasonStartDate": "2025-03-27", "seasonId": "2025" } } ] } ``` ### Get a player Get one person's record (a player, a coach or an umpire): full name, position, bats and throws, height and weight, birthplace, debut and current team. **Inputs** - Player (`person_id`, text, required): The player's id. Search for players returns one per match, and it is also the number in an MLB player page URL. - Season (`season`, text): Which season to read. Defaults to the current season. - Keep accents in names (`accent`, true/false): On (the default), names keep their accents. Off, they are returned unaccented. - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "people": [ { "active": true, "batSide": { "code": "L", "description": "Left" }, "birthCountry": "Japan", "birthDate": "1994-07-05", "currentAge": 31, "firstName": "Shohei", "fullName": "Shohei Ohtani", "height": "6' 4\"", "id": 660271, "lastName": "Ohtani", "link": "/api/v1/people/660271", "mlbDebutDate": "2018-03-29", "pitchHand": { "code": "R", "description": "Right" }, "primaryNumber": "17", "primaryPosition": { "abbreviation": "TWP", "code": "Y", "name": "Two-Way Player", "type": "Two-Way Player" }, "weight": 210 } ] } ``` ### Get a player's line from a game Get how one player did in one particular game: their batting, pitching and fielding line for that day. **Inputs** - Player (`person_id`, text, required): The player's id. Search for players returns one per match, and it is also the number in an MLB player page URL. - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. - Stat groups (`group`, list): Which kinds of statistics to return. Leave blank for every group the player has. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "stats": [ { "group": { "displayName": "hitting" }, "splits": [ { "gameType": "R", "league": { "id": 104, "name": "National League" }, "player": { "fullName": "Shohei Ohtani", "id": 660271 }, "season": "2024", "sport": { "abbreviation": "MLB", "id": 1 }, "stat": { "atBats": 636, "avg": ".310", "doubles": 38, "gamesPlayed": 159, "hits": 197, "homeRuns": 54, "obp": ".390", "ops": "1.036", "rbi": 130, "runs": 134, "slg": ".646", "stolenBases": 59, "triples": 7 }, "team": { "id": 119, "name": "Los Angeles Dodgers" } } ], "totalSplits": 1, "type": { "displayName": "season" } } ] } ``` ### Get a player's stats Get one player's statistics in whichever shape you need: a season line, a career total, year by year, a game log, a pitch log, splits against a given opponent, or by date range. Situational filters narrow it further: only with runners in scoring position, only against left-handers, only at home. **Inputs** - Player (`person_id`, text, required): The player's id. Search for players returns one per match, and it is also the number in an MLB player page URL. - Stat splits (`stats`, list, required): How to slice the statistics: a season total, a career total, a game log, year by year, and so on. One or more of: `season`, `career`, `yearByYear` (Year by year), `gameLog` (Game log), `statSplits` (Stat splits), `advanced`, `standard`, `projected`, `projectedRos` (Projected rest of season), `yearByYearAdvanced` (Year by year advanced), and 51 more. Default: `["season"]`. - Stat groups (`group`, list): Which kinds of statistics to return. Leave blank for every group the player has. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. - Season (`season`, text): Which season to read. Defaults to the current season. - Seasons (`seasons`, list): Which seasons to read. Leave blank for the current season. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - League (`league_id`, text): Only return results for this league. Leave blank for all leagues. - Game types (`game_types`, list): Only include games of these types. Leave blank to include every type. One or more of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Opposing team (`opposing_team_id`, text): Only count games against this team. Pair it with the "Vs team" split. - Opposing player (`opposing_player_id`, text): Only count matchups against this player. Pair it with the "Vs player" split. - Situations (`sit_codes`, list): Only count plate appearances in these situations, such as home games or with runners in scoring position. - Match every situation (`combine_sits`, true/false): On, a plate appearance counts only when it matches every situation you chose. Off (the default), any one of them is enough. Default: `false`. - Batter handedness (`bat_side`, text): Only count plate appearances by batters of this side. One of: `R` (Right-handed batters), `L` (Left-handed batters). - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Last N days (`days_back`, number): Only count the last this many days of games, ending yesterday. From 1 to 365. - Last N games (`games_back`, number): Only count the player's last this many games. Pair it with the "Last X games" split. From 1 to 162. - Number of results (`limit`, number): How many rows to return for a split that produces many, such as a game log. Up to 1000. From 1 to 1000. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "stats": [ { "group": { "displayName": "hitting" }, "splits": [ { "gameType": "R", "league": { "id": 104, "name": "National League" }, "player": { "fullName": "Shohei Ohtani", "id": 660271 }, "season": "2024", "sport": { "abbreviation": "MLB", "id": 1 }, "stat": { "atBats": 636, "avg": ".310", "doubles": 38, "gamesPlayed": 159, "hits": 197, "homeRuns": 54, "obp": ".390", "ops": "1.036", "rbi": 130, "runs": 134, "slg": ".646", "stolenBases": 59, "triples": 7 }, "team": { "id": 119, "name": "Los Angeles Dodgers" } } ], "totalSplits": 1, "type": { "displayName": "season" } } ] } ``` ### Get a team Get one team's record: its names and abbreviations, home ballpark, spring training home, league, division and first year of play. **Inputs** - Team (`team_id`, text, required): Which team to read. - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "teams": [ { "abbreviation": "NYY", "active": true, "division": { "id": 201, "link": "/api/v1/divisions/201", "name": "American League East" }, "firstYearOfPlay": "1903", "id": 147, "league": { "id": 103, "link": "/api/v1/league/103", "name": "American League" }, "link": "/api/v1/teams/147", "locationName": "Bronx", "name": "New York Yankees", "sport": { "id": 1, "link": "/api/v1/sports/1", "name": "Major League Baseball" }, "teamCode": "nya", "teamName": "Yankees", "venue": { "id": 3313, "link": "/api/v1/venues/3313", "name": "Yankee Stadium" } } ] } ``` ### Get a team's leaders Get the players who lead one team in a statistic: who hit the most home runs for the Yankees this season, and by how much. **Inputs** - Team (`team_id`, text, required): Which team to read. - Statistics (`leader_categories`, list, required): Which statistics to rank by. One or more of: `homeRuns` (Home runs), `battingAverage` (Batting average), `runsBattedIn` (Runs batted in), `hits`, `runs`, `stolenBases` (Stolen bases), `onBasePercentage` (On base percentage), `sluggingPercentage` (Slugging percentage), `onBasePlusSlugging` (On base plus slugging), `earnedRunAverage` (Earned run average), and 60 more. Default: `["homeRuns"]`. - Season (`season`, text): Which season to read. Defaults to the current season. - Game types (`leader_game_types`, list): Only count games of these types towards the leaderboard. Leave blank for the regular season. One or more of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Stat groups (`stat_group`, list): Which kinds of statistics to rank. Defaults to hitting. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. - Number of results (`limit`, number): How many leaders to return, from 1 to 1000. Defaults to 10. From 1 to 1000. Default: `10`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "teamLeaders": [ { "leaderCategory": "homeRuns", "leaders": [ { "person": { "fullName": "Aaron Judge", "id": 592450 }, "rank": 1, "team": { "id": 147, "name": "New York Yankees" }, "value": "58" } ], "season": "2024", "statGroup": "hitting" } ] } ``` ### Get a team's roster Get the players on a team, each with their jersey number, position and roster status. Choose which roster: the active one, the 40-man, a full season including everyone who passed through, the depth chart, non-roster invitees, or the all-time roster. **Inputs** - Team (`team_id`, text, required): Which team to read. - Roster (`roster_type`, text): Which roster to read. Defaults to the active roster. One of: `active` (Active roster), `40Man` (40-man roster), `fullSeason` (Full season (active and inactive)), `fullRoster` (Full roster (active and inactive, all time)), `nonRosterInvitees` (Non-roster invitees), `allTime` (All-time roster), `depthChart` (Depth chart), `gameday` (Day-of-game roster), `coach` (Coaches). Default: `active`. - Season (`season`, text): Which season to read. Defaults to the current season. - Date (`date`, date): A single date to read. - Game type (`game_type`, text): Only count games of this type. Leave blank to include every type. One of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "roster": [ { "jerseyNumber": "99", "parentTeamId": 147, "person": { "fullName": "Aaron Judge", "id": 592450, "link": "/api/v1/people/592450" }, "position": { "abbreviation": "CF", "code": "8", "name": "Outfielder", "type": "Outfielder" }, "status": { "code": "A", "description": "Active" } } ], "rosterType": "active", "teamId": 147 } ``` ### Get a team's stats Get one team's own statistics, in whichever split you ask for: a season total, year by year, a game log, home and away, by month, and so on. **Inputs** - Team (`team_id`, text, required): Which team to read. - Stat splits (`stats`, list, required): How to slice the statistics: a season total, a career total, a game log, year by year, and so on. One or more of: `season`, `career`, `yearByYear` (Year by year), `gameLog` (Game log), `statSplits` (Stat splits), `advanced`, `standard`, `projected`, `projectedRos` (Projected rest of season), `yearByYearAdvanced` (Year by year advanced), and 51 more. Default: `["season"]`. - Stat groups (`group`, list, required): Which kinds of statistics to return. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. Default: `["hitting"]`. - Season (`season`, text): Which season to read. Defaults to the current season. - Game type (`game_type`, text): Only count games of this type. Leave blank to include every type. One of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Opponent (`opposing_team_id`, text): Only count games against this opponent. - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "stats": [ { "group": { "displayName": "hitting" }, "splits": [ { "gameType": "R", "league": { "id": 104, "name": "National League" }, "player": { "fullName": "Shohei Ohtani", "id": 660271 }, "season": "2024", "sport": { "abbreviation": "MLB", "id": 1 }, "stat": { "atBats": 636, "avg": ".310", "doubles": 38, "gamesPlayed": 159, "hits": 197, "homeRuns": 54, "obp": ".390", "ops": "1.036", "rbi": 130, "runs": 134, "slg": ".646", "stolenBases": 59, "triples": 7 }, "team": { "id": 119, "name": "Los Angeles Dodgers" } } ], "totalSplits": 1, "type": { "displayName": "season" } } ] } ``` ### Get All-Star write-ins Get the write-in candidates on a league's All-Star ballot: the players fans named who were not printed on it. **Inputs** - League (`league_id`, text, required): Which league to read. - Season (`season`, text, required): Which season to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "people": [ { "active": true, "batSide": { "code": "L", "description": "Left" }, "birthCountry": "Japan", "birthDate": "1994-07-05", "currentAge": 31, "firstName": "Shohei", "fullName": "Shohei Ohtani", "height": "6' 4\"", "id": 660271, "lastName": "Ohtani", "link": "/api/v1/people/660271", "mlbDebutDate": "2018-03-29", "pitchHand": { "code": "R", "description": "Right" }, "primaryNumber": "17", "primaryPosition": { "abbreviation": "TWP", "code": "Y", "name": "Two-Way Player", "type": "Two-Way Player" }, "weight": 210 } ] } ``` ### Get an award Get one award's record by its id: its full name, the organization that gives it, and the notes MLB files it under. **Inputs** - Award (`award_id`, text, required): Which award to read. - Organizations (`org_id`, list): Only return the award as given by these organizations. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "awards": [ { "id": "ALMVP", "name": "AL Most Valuable Player" } ], "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt" } ``` ### Get attendance Get how many people came through the gates: a team's or a league's total, average, high and low attendance, split home and away. **Inputs** - Teams (`team_ids`, list): Only return results for these teams. Leave blank for all teams. - Leagues (`league_ids`, list): Only return results for these leagues. Leave blank for all leagues. - Seasons (`seasons`, list): Which seasons to read. Leave blank for the current season. - Game types (`game_types`, list): Only include games of these types. Leave blank to include every type. One or more of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Date (`date`, date): A single date to read. - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "aggregateTotals": { "attendanceTotal": 3415244 }, "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "records": [ { "attendanceAverage": 42163, "attendanceHigh": 47399, "attendanceTotal": 3415244, "openingsTotal": 81, "openingsTotalHome": 81, "season": "2024", "team": { "id": 147, "name": "New York Yankees" } } ] } ``` ### Get broadcasters Look broadcasters up by id and get their name, call sign, whether they are TV or radio, and whether they are local or national. Get the schedule with broadcasts included to find the ids. **Inputs** - Broadcaster IDs (`broadcaster_ids`, list, required): The broadcaster ids to look up. A game's broadcasts carry them. **Outputs** - `broadcasts` (list) **Example output** ```json { "broadcasts": [ { "activeStatus": true, "availability": { "availabilityCode": "local_in_market", "availabilityText": "Local (In Market)" }, "callSign": "SNY", "id": 741, "name": "SNY", "teamId": 121, "type": "TV" } ] } ``` ### Get grouped stats Get statistics rolled up by a dimension of your choosing (by month, by ballpark, by opponent, by pitch type, by count) instead of one flat row per player. Use it to answer "how does this hitter do against sliders" in one step. **Inputs** - Stat splits (`stats`, list, required): How to slice the statistics: a season total, a career total, a game log, year by year, and so on. One or more of: `season`, `career`, `yearByYear` (Year by year), `gameLog` (Game log), `statSplits` (Stat splits), `advanced`, `standard`, `projected`, `projectedRos` (Projected rest of season), `yearByYearAdvanced` (Year by year advanced), and 51 more. Default: `["season"]`. - Stat groups (`group`, list, required): Which kinds of statistics to return. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. Default: `["hitting"]`. - Group by (`group_by`, list): Which dimensions to roll the statistics up by. One or more of: `player`, `team`, `season`, `game`, `date`, `month`, `dayOfWeek` (Day of week), `dayNight` (Day/night), `gameType` (Game type), `homeAway` (Home/away), and 25 more. - Stat blocks (`stat_fields`, list): Which blocks of statistics to fill in: the standard line, the advanced one, tracking data, and so on. One or more of: `standard`, `advanced`, `tracking`, `expected`, `sabermetrics`, `rankings`, `percentiles`, `projected`. - Sort within block (`sort_field`, text): Which of the chosen blocks to sort on when you asked for more than one. One of: `standard`, `advanced`, `tracking`, `expected`, `sabermetrics`, `rankings`, `percentiles`, `projected`. - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - League (`league_id`, text): Only return results for this league. Leave blank for all leagues. - Team (`team_id`, text): Only return results for this team. Leave blank for all teams. - Player (`person_id`, text): Only return this player's rows. - Game type (`game_type`, text): Only count games of this type. Leave blank to include every type. One of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Player pool (`player_pool`, text): Which players to include. Qualified means only those with enough plate appearances or innings to appear on a leaderboard. One of: `ALL` (All players), `QUALIFIED` (Qualified players only), `ROOKIES`, `QUALIFIED_ROOKIES` (Qualified rookies). - Sort by (`sort_stat`, text): Which statistic to sort the rows by. One of: `homeRuns` (Home runs), `battingAverage` (Batting average), `runsBattedIn` (Runs batted in), `hits`, `runs`, `stolenBases` (Stolen bases), `onBasePercentage` (On base percentage), `sluggingPercentage` (Slugging percentage), `onBasePlusSlugging` (On base plus slugging), `earnedRunAverage` (Earned run average), and 60 more. - Sort direction (`order`, text): Whether to list the highest or the lowest values first. One of: `desc` (Highest first), `asc` (Lowest first). - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Number of results (`limit`, number): How many rows to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`. - Rows to skip (`offset`, number): How many rows to skip before returning results. Use it with the number of results to page through a long list (0, then 50, then 100, ...). From 0 to 1000000. Default: `0`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "stats": [ { "group": { "displayName": "hitting" }, "splits": [ { "gameType": "R", "league": { "id": 104, "name": "National League" }, "player": { "fullName": "Shohei Ohtani", "id": 660271 }, "season": "2024", "sport": { "abbreviation": "MLB", "id": 1 }, "stat": { "atBats": 636, "avg": ".310", "doubles": 38, "gamesPlayed": 159, "hits": 197, "homeRuns": 54, "obp": ".390", "ops": "1.036", "rbi": 130, "runs": 134, "slg": ".646", "stolenBases": 59, "triples": 7 }, "team": { "id": 119, "name": "Los Angeles Dodgers" } } ], "totalSplits": 1, "type": { "displayName": "season" } } ] } ``` ### Get pace of play Get how long games take: average game time, runs and pitches per game, and time per plate appearance, for a team, a league or a whole level of baseball. **Inputs** - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - Teams (`team_ids`, list): Only return results for these teams. Leave blank for all teams. - Leagues (`league_ids`, list): Only return results for these leagues. Leave blank for all leagues. - Ballparks (`venue_ids`, list): Only return results played at these ballparks. - Game type (`game_type`, text): Only count games of this type. Leave blank to include every type. One of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Level (`org_type`, text): Whether to report by team, by league or by sport. One of: `T` (Team), `L` (League), `S` (Sport). - Include child organizations (`include_children`, true/false): On, a sport's leagues and teams are reported alongside the sport itself. - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "sports": [ { "hitsPer9Inn": 8.42, "pitchesPer9Inn": 146.13, "runsPer9Inn": 4.39, "season": "2024", "sport": { "id": 1, "name": "Major League Baseball" }, "timePerGame": "2:36", "totalGames": 2429 } ] } ``` ### Get postseason series Get the postseason grouped into its series rather than as a flat list of games, so a workflow can read a matchup and its series status in one step. **Inputs** - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - Team (`team_id`, text): Only return results for this team. Leave blank for all teams. - Game types (`game_types`, list): Only include games of these types. Leave blank to include every type. One or more of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Series number (`series_number`, number): Only return one series within the round, numbered from 1. From 1 to 20. - Date (`date`, date): A single date to read. - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "series": [ { "games": [ { "gameDate": "2025-09-01T17:10:00Z", "gameGuid": "d1b0a9c4-3d5f-4a2b-9a41-2f2b7d4c1a55", "gamePk": 776501, "gameType": "W", "link": "/api/v1/game/776501/feed/live", "officialDate": "2025-09-01", "season": "2025", "status": { "abstractGameState": "Final", "codedGameState": "F", "detailedState": "Final", "statusCode": "F" }, "teams": { "away": { "isWinner": true, "score": 4, "team": { "id": 121, "name": "New York Mets" } }, "home": { "isWinner": false, "score": 2, "team": { "id": 116, "name": "Detroit Tigers" } } }, "venue": { "id": 2394, "name": "Comerica Park" } } ], "series": { "gameType": "W", "id": 1 } } ], "totalItems": 1 } ``` ### Get postseason tune-in times Get the postseason tune-in schedule: when each game starts and which broadcasters are carrying it. **Inputs** - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - Team (`team_id`, text): Only return results for this team. Leave blank for all teams. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "dates": [ { "date": "2024-10-25", "games": [ { "gameDate": "2025-09-01T17:10:00Z", "gameGuid": "d1b0a9c4-3d5f-4a2b-9a41-2f2b7d4c1a55", "gamePk": 776501, "gameType": "R", "link": "/api/v1/game/776501/feed/live", "officialDate": "2025-09-01", "season": "2025", "status": { "abstractGameState": "Final", "codedGameState": "F", "detailedState": "Final", "statusCode": "F" }, "teams": { "away": { "isWinner": true, "score": 4, "team": { "id": 121, "name": "New York Mets" } }, "home": { "isWinner": false, "score": 2, "team": { "id": 116, "name": "Detroit Tigers" } } }, "venue": { "id": 2394, "name": "Comerica Park" } } ] } ], "totalItems": 1 } ``` ### Get record highs and lows Get the best and worst single performances on record for a statistic: the most home runs in a game by a player, the most runs by a team, the longest game. Choose whether to rank player, team or game records. **Inputs** - Record type (`high_low_type`, text, required): Whether to rank player, team or game records. One of: `player` (Player records), `team` (Team records), `game` (Game records). Default: `player`. - Statistics (`sort_stat`, list, required): Which statistics to rank records by. One or more of: `homeRuns` (Home runs), `hits`, `runs`, `rbi` (Runs batted in), `atBats` (At bats), `plateAppearances` (Plate appearances), `hitsRisp` (Hits with runners in scoring position), `totalBases` (Total bases), `doubles`, `triples`, and 24 more. Default: `["homeRuns"]`. - Stat groups (`stat_group`, list): Which kinds of statistics to rank. Defaults to hitting. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. - Seasons (`seasons`, list): Which seasons to read. Leave blank for the current season. - Game types (`game_types`, list): Only include games of these types. Leave blank to include every type. One or more of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - League (`league_id`, text): Only return results for this league. Leave blank for all leagues. - Team (`team_id`, text): Only return results for this team. Leave blank for all teams. - Number of results (`limit`, number): How many leaders to return, from 1 to 1000. Defaults to 10. From 1 to 1000. Default: `10`. - Rows to skip (`offset`, number): How many rows to skip before returning results. Use it with the number of results to page through a long list (0, then 50, then 100, ...). From 0 to 1000000. Default: `0`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "highLowResults": [ { "group": { "displayName": "hitting" }, "splits": [ { "date": "2024-08-28", "game": { "gamePk": 745541 }, "gameType": "R", "opponent": { "id": 143, "name": "Philadelphia Phillies" }, "player": { "fullName": "Yordan Alvarez", "id": 670541 }, "rank": 1, "season": "2024", "stat": { "homeRuns": 3 }, "team": { "id": 117, "name": "Houston Astros" } } ], "splitsTiedWithLimit": [], "totalSplits": 303 } ] } ``` ### Get replay review records Get how replay review went in a season: how many calls each team challenged, how many were overturned, and how long the reviews took. **Inputs** - Sport level (`sport_id`, text, required): Which level of baseball to read. Default: `1`. - Season (`season`, text, required): Which season to read. - Game type (`game_type`, text, required): Which games to report on. One of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). Default: `R`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "exemptions": [], "splits": [ { "awayTeam": { "id": 145, "link": "/api/v1/teams/145" }, "date": "2024-06-04", "homeTeam": { "id": 112, "link": "/api/v1/teams/112" }, "season": "2024", "stat": { "play": { "details": { "description": "White Sox challenged (tag play), call on the field was upheld.", "hasReview": true }, "reviewDetails": { "challengeTeamId": 145, "isOverturned": false, "reviewType": "MA" } } } } ] } ``` ### Get several players Get the records of several people in one request, which is much kinder to MLB's servers than looping one player at a time over a roster. **Inputs** - Player IDs (`person_ids`, list, required): The ids of the people to fetch. - Season (`season`, text): Which season to read. Defaults to the current season. - Stat groups (`group`, list): Which kinds of statistics to return. Leave blank for every group the player has. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. - Keep accents in names (`accent`, true/false): On (the default), names keep their accents. Off, they are returned unaccented. - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "people": [ { "active": true, "batSide": { "code": "L", "description": "Left" }, "birthCountry": "Japan", "birthDate": "1994-07-05", "currentAge": 31, "firstName": "Shohei", "fullName": "Shohei Ohtani", "height": "6' 4\"", "id": 660271, "lastName": "Ohtani", "link": "/api/v1/people/660271", "mlbDebutDate": "2018-03-29", "pitchHand": { "code": "R", "description": "Right" }, "primaryNumber": "17", "primaryPosition": { "abbreviation": "TWP", "code": "Y", "name": "Two-Way Player", "type": "Two-Way Player" }, "weight": 210 } ] } ``` ### Get stat leaders Get the players who lead a statistic, ranked, with each leader's value and team: the league leaderboard for home runs, ERA, stolen bases or any of the other categories. **Inputs** - Statistics (`leader_categories`, list, required): Which statistics to rank by. One or more of: `homeRuns` (Home runs), `battingAverage` (Batting average), `runsBattedIn` (Runs batted in), `hits`, `runs`, `stolenBases` (Stolen bases), `onBasePercentage` (On base percentage), `sluggingPercentage` (Slugging percentage), `onBasePlusSlugging` (On base plus slugging), `earnedRunAverage` (Earned run average), and 60 more. Default: `["homeRuns"]`. - Season (`season`, text): Which season to read. Defaults to the current season. - Stat groups (`stat_group`, list): Which kinds of statistics to rank. Defaults to hitting. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - League (`league_id`, text): Only return results for this league. Leave blank for all leagues. - Team (`team_id`, text): Only return results for this team. Leave blank for all teams. - Game types (`leader_game_types`, list): Only count games of these types towards the leaderboard. Leave blank for the regular season. One or more of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Player pool (`player_pool`, text): Which players to include. Qualified means only those with enough plate appearances or innings to appear on a leaderboard. One of: `ALL` (All players), `QUALIFIED` (Qualified players only), `ROOKIES`, `QUALIFIED_ROOKIES` (Qualified rookies). - Positions (`position`, list): Only include players at these positions. One or more of: `1` (Pitcher (P)), `2` (Catcher (C)), `3` (First base (1B)), `4` (Second base (2B)), `5` (Third base (3B)), `6` (Shortstop (SS)), `7` (Left field (LF)), `8` (Center field (CF)), `9` (Right field (RF)), `10` (Designated hitter (DH)), and 18 more. - Stat split (`stat_type`, text): Which split to rank on. Leave blank for season totals. One of: `season`, `career`, `yearByYear` (Year by year), `gameLog` (Game log), `statSplits` (Stat splits), `advanced`, `standard`, `projected`, `projectedRos` (Projected rest of season), `yearByYearAdvanced` (Year by year advanced), and 51 more. - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Number of results (`limit`, number): How many leaders to return, from 1 to 1000. Defaults to 10. From 1 to 1000. Default: `10`. - Rows to skip (`offset`, number): How many rows to skip before returning results. Use it with the number of results to page through a long list (0, then 50, then 100, ...). From 0 to 1000000. Default: `0`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "leagueLeaders": [ { "leaderCategory": "homeRuns", "leaders": [ { "league": { "id": 103, "name": "American League" }, "person": { "fullName": "Aaron Judge", "id": 592450 }, "rank": 1, "team": { "id": 147, "name": "New York Yankees" }, "value": "58" } ], "season": "2024", "statGroup": "hitting" } ] } ``` ### Get stats Get a table of statistics across players or teams: the general-purpose stats query. Pick the split and the stat group, then narrow by season, team, league, position, date range or situation, and sort by whichever statistic you like. **Inputs** - Stat splits (`stats`, list, required): How to slice the statistics: a season total, a career total, a game log, year by year, and so on. One or more of: `season`, `career`, `yearByYear` (Year by year), `gameLog` (Game log), `statSplits` (Stat splits), `advanced`, `standard`, `projected`, `projectedRos` (Projected rest of season), `yearByYearAdvanced` (Year by year advanced), and 51 more. Default: `["season"]`. - Stat groups (`group`, list, required): Which kinds of statistics to return. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. Default: `["hitting"]`. - Season (`season`, text): Which season to read. Defaults to the current season. - Seasons (`seasons`, list): Which seasons to read. Leave blank for the current season. - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - League (`league_id`, text): Only return results for this league. Leave blank for all leagues. - Team (`team_id`, text): Only return results for this team. Leave blank for all teams. - Player (`person_id`, text): Only return this player's rows. - Game (`game_pk`, text): Only return rows from this game. - Game type (`game_type`, text): Only count games of this type. Leave blank to include every type. One of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Positions (`position`, list): Only include players at these positions. One or more of: `1` (Pitcher (P)), `2` (Catcher (C)), `3` (First base (1B)), `4` (Second base (2B)), `5` (Third base (3B)), `6` (Shortstop (SS)), `7` (Left field (LF)), `8` (Center field (CF)), `9` (Right field (RF)), `10` (Designated hitter (DH)), and 18 more. - Player pool (`player_pool`, text): Which players to include. Qualified means only those with enough plate appearances or innings to appear on a leaderboard. One of: `ALL` (All players), `QUALIFIED` (Qualified players only), `ROOKIES`, `QUALIFIED_ROOKIES` (Qualified rookies). - Sort by (`sort_stat`, text): Which statistic to sort the rows by. One of: `homeRuns` (Home runs), `battingAverage` (Batting average), `runsBattedIn` (Runs batted in), `hits`, `runs`, `stolenBases` (Stolen bases), `onBasePercentage` (On base percentage), `sluggingPercentage` (Slugging percentage), `onBasePlusSlugging` (On base plus slugging), `earnedRunAverage` (Earned run average), and 60 more. - Sort direction (`order`, text): Whether to list the highest or the lowest values first. One of: `desc` (Highest first), `asc` (Lowest first). - Situations (`sit_codes`, list): Only count plate appearances in these situations, such as home games or with runners in scoring position. - Match every situation (`combine_sits`, true/false): On, a plate appearance counts only when it matches every situation you chose. Off (the default), any one of them is enough. Default: `false`. - Opposing team (`opposing_team_id`, text): Only count games against this team. - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Last N days (`days_back`, number): Only count the last this many days of games, ending yesterday. From 1 to 365. - Last N games (`games_back`, number): Only count the last this many games played. From 1 to 162. - Number of results (`limit`, number): How many rows to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`. - Rows to skip (`offset`, number): How many rows to skip before returning results. Use it with the number of results to page through a long list (0, then 50, then 100, ...). From 0 to 1000000. Default: `0`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "stats": [ { "group": { "displayName": "hitting" }, "splits": [ { "gameType": "R", "league": { "id": 104, "name": "National League" }, "player": { "fullName": "Shohei Ohtani", "id": 660271 }, "season": "2024", "sport": { "abbreviation": "MLB", "id": 1 }, "stat": { "atBats": 636, "avg": ".310", "doubles": 38, "gamesPlayed": 159, "hits": 197, "homeRuns": 54, "obp": ".390", "ops": "1.036", "rbi": 130, "runs": 134, "slg": ".646", "stolenBases": 59, "triples": 7 }, "team": { "id": 119, "name": "Los Angeles Dodgers" } } ], "totalSplits": 1, "type": { "displayName": "season" } } ] } ``` ### Get the All-MLB ballot Get the whole-sport All-MLB ballot for a season: the candidates for the season-ending All-MLB team, across both leagues. **Inputs** - Sport level (`sport_id`, text, required): Which level of baseball to read. Default: `1`. - Season (`season`, text, required): Which season to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "people": [ { "active": true, "batSide": { "code": "L", "description": "Left" }, "birthCountry": "Japan", "birthDate": "1994-07-05", "currentAge": 31, "firstName": "Shohei", "fullName": "Shohei Ohtani", "height": "6' 4\"", "id": 660271, "lastName": "Ohtani", "link": "/api/v1/people/660271", "mlbDebutDate": "2018-03-29", "pitchHand": { "code": "R", "description": "Right" }, "primaryNumber": "17", "primaryPosition": { "abbreviation": "TWP", "code": "Y", "name": "Two-Way Player", "type": "Two-Way Player" }, "weight": 210 } ] } ``` ### Get the All-Star ballot Get a league's All-Star ballot for a season: the candidates at each position, with their team and their ballot position. **Inputs** - League (`league_id`, text, required): Which league to read. - Season (`season`, text, required): Which season to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "people": [ { "active": true, "batSide": { "code": "L", "description": "Left" }, "birthCountry": "Japan", "birthDate": "1994-07-05", "currentAge": 31, "firstName": "Shohei", "fullName": "Shohei Ohtani", "height": "6' 4\"", "id": 660271, "lastName": "Ohtani", "link": "/api/v1/people/660271", "mlbDebutDate": "2018-03-29", "pitchHand": { "code": "R", "description": "Right" }, "primaryNumber": "17", "primaryPosition": { "abbreviation": "TWP", "code": "Y", "name": "Two-Way Player", "type": "Two-Way Player" }, "weight": 210 } ] } ``` ### Get the All-Star Final Vote Get a league's All-Star Final Vote candidates: the players competing for the last roster spot. **Inputs** - League (`league_id`, text, required): Which league to read. - Season (`season`, text, required): Which season to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "people": [ { "active": true, "batSide": { "code": "L", "description": "Left" }, "birthCountry": "Japan", "birthDate": "1994-07-05", "currentAge": 31, "firstName": "Shohei", "fullName": "Shohei Ohtani", "height": "6' 4\"", "id": 660271, "lastName": "Ohtani", "link": "/api/v1/people/660271", "mlbDebutDate": "2018-03-29", "pitchHand": { "code": "R", "description": "Right" }, "primaryNumber": "17", "primaryPosition": { "abbreviation": "TWP", "code": "Y", "name": "Two-Way Player", "type": "Two-Way Player" }, "weight": 210 } ] } ``` ### Get the latest draft pick Get the pick just made in a draft and the next five teams on the clock: what a live draft tracker reads. **Inputs** - Draft year (`year`, text, required): Which draft to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "nextUp": [ { "pickNumber": 616, "pickRound": "20" } ], "number": 615, "pick": { "bisPlayerId": 831142, "isDrafted": true, "isPass": false, "person": { "fullName": "Travis Bazzana", "id": 700123, "primaryPosition": { "abbreviation": "2B" } }, "pickNumber": 1, "pickRound": "1", "pickValue": "10570600", "rank": 1, "roundPickNumber": 1, "school": { "country": "USA", "name": "Oregon State University", "state": "OR" }, "signingBonus": "9200000", "team": { "id": 114, "name": "Cleveland Guardians" } } } ``` ### Get the leading teams Get the teams that lead a statistic: which club scored the most runs or allowed the fewest. **Inputs** - Statistics (`leader_categories`, list, required): Which statistics to rank by. One or more of: `homeRuns` (Home runs), `battingAverage` (Batting average), `runsBattedIn` (Runs batted in), `hits`, `runs`, `stolenBases` (Stolen bases), `onBasePercentage` (On base percentage), `sluggingPercentage` (Slugging percentage), `onBasePlusSlugging` (On base plus slugging), `earnedRunAverage` (Earned run average), and 60 more. Default: `["homeRuns"]`. - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - League (`league_id`, text): Only return results for this league. Leave blank for all leagues. - Game types (`leader_game_types`, list): Only count games of these types towards the leaderboard. Leave blank for the regular season. One or more of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Stat groups (`stat_group`, list): Which kinds of statistics to rank. Defaults to hitting. One or more of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. - Number of results (`limit`, number): How many leaders to return, from 1 to 1000. Defaults to 10. From 1 to 1000. Default: `10`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "leagueLeaders": [ { "leaderCategory": "homeRuns", "leaders": [ { "rank": 1, "team": { "id": 147, "name": "New York Yankees" }, "value": "237" } ], "season": "2024", "statGroup": "hitting" } ] } ``` ### Get the postseason schedule Get a season's postseason games (Wild Card round through the World Series) with the same per-game detail as the regular schedule. **Inputs** - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - Team (`team_id`, text): Only return results for this team. Leave blank for all teams. - Game types (`game_types`, list): Only include games of these types. Leave blank to include every type. One or more of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Series number (`series_number`, number): Only return one series within the round, numbered from 1. Leave blank for all of them. From 1 to 20. - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "dates": [ { "date": "2024-10-25", "games": [ { "gameDate": "2025-09-01T17:10:00Z", "gameGuid": "d1b0a9c4-3d5f-4a2b-9a41-2f2b7d4c1a55", "gamePk": 776501, "gameType": "W", "link": "/api/v1/game/776501/feed/live", "officialDate": "2025-09-01", "season": "2025", "status": { "abstractGameState": "Final", "codedGameState": "F", "detailedState": "Final", "statusCode": "F" }, "teams": { "away": { "isWinner": true, "score": 4, "team": { "id": 121, "name": "New York Mets" } }, "home": { "isWinner": false, "score": 2, "team": { "id": 116, "name": "Detroit Tigers" } } }, "venue": { "id": 2394, "name": "Comerica Park" } } ] } ], "totalItems": 1 } ``` ### Get the schedule Get the games on a date or across a date range, with each game's teams, start time, ballpark, status and final score. This is the usual starting point: every game comes back with the game id the boxscore, linescore and play-by-play actions take. Switch the schedule type to All events to see the non-game events on the calendar too, such as All-Star Weekend and ballpark tours. **Inputs** - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - Schedule type (`schedule_type`, text): Games only (the default), or every event on the calendar. One of: `games`, `events` (All events (games plus non-game events)), `xref` (Cross-referenced games). Default: `games`. - Date (`date`, date): A single date to read. - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Teams (`team_ids`, list): Only return results for these teams. Leave blank for all teams. - Opponent (`opponent_id`, text): Only return games against this opponent. Use it together with a team. - Leagues (`league_ids`, list): Only return results for these leagues. Leave blank for all leagues. - Ballparks (`venue_ids`, list): Only return results played at these ballparks. - Game IDs (`game_pks`, list): Only return these specific games. - Game types (`game_types`, list): Only include games of these types. Leave blank to include every type. One or more of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Event types (`schedule_event_types`, list): Only return these kinds of non-game event. Applies when the schedule type is "All events". One or more of: `A` (All-Star Weekend Event), `T` (Team Event), `E` (Exhibition), `Z` (Postseason Games), `Y` (Spring Training Games), `W` (Pitchers & Catchers Report), `X` (Full Squad Reports), `H` (STH Events), `B` (Ballpark Tours), `I` (Important Dates), and 9 more. - Season (`season`, text): Which season to read. Defaults to the current season. - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "dates": [ { "date": "2025-09-01", "games": [ { "gameDate": "2025-09-01T17:10:00Z", "gameGuid": "d1b0a9c4-3d5f-4a2b-9a41-2f2b7d4c1a55", "gamePk": 776501, "gameType": "R", "link": "/api/v1/game/776501/feed/live", "officialDate": "2025-09-01", "season": "2025", "status": { "abstractGameState": "Final", "codedGameState": "F", "detailedState": "Final", "statusCode": "F" }, "teams": { "away": { "isWinner": true, "score": 4, "team": { "id": 121, "name": "New York Mets" } }, "home": { "isWinner": false, "score": 2, "team": { "id": 116, "name": "Detroit Tigers" } } }, "venue": { "id": 2394, "name": "Comerica Park" } } ], "totalGames": 1 } ], "totalGames": 1, "totalItems": 1 } ``` ### Get the standings Get the table for one or more leagues: each team's record, games behind, streak, run differential and clinch status. Choose the kind of table: the division race, the wild card picture, spring training, or a split-season half. **Inputs** - Leagues (`league_id`, list, required): Which leagues to read the table for. The American League and the National League are the two MLB ones. - Table (`standings_type`, text): Which table to read. Defaults to the regular season standings. One of: `regularSeason` (Regular season), `wildCard` (Wild card), `divisionLeaders` (Division leaders), `wildCardWithLeaders` (Wild card with division leaders), `firstHalf` (First half (split-season leagues only)), `secondHalf` (Second half (split-season leagues only)), `currentHalf` (Current half), `springTraining` (Spring training), `postseason`, `byDivision` (By division), and 3 more. Default: `regularSeason`. - Season (`season`, text): Which season to read. Defaults to the current season. - As at date (`date`, date): Read the table as it stood on this date rather than today. - Team (`team_id`, text): Only return results for this team. Leave blank for all teams. - Include major league teams (`include_mlb`, true/false): On, major league clubs are included in the "By organization" table alongside their affiliates. - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "records": [ { "division": { "id": 201, "name": "American League East" }, "league": { "id": 103, "name": "American League" }, "standingsType": "regularSeason", "teamRecords": [ { "divisionRank": "1", "gamesBack": "-", "leagueRank": "1", "losses": 68, "runDifferential": 145, "streak": { "streakCode": "W2" }, "team": { "id": 147, "name": "New York Yankees" }, "winningPercentage": ".580", "wins": 94 } ] } ] } ``` ### List a game's timestamps List every moment a game's feed can be rewound to, oldest first. Feed each one to Get a game's live feed to replay the game state by state. **Inputs** - Game (`game_pk`, text, required): The game's id (its gamePk). Get the schedule returns one per game, and you can also paste an MLB Gameday URL. **Outputs** - `timestamps` (list) **Example output** ```json { "timestamps": [ "20250901_170500", "20250901_170532", "20250901_201500" ] } ``` ### List a player's awards List every award one player has won, with the season and the team they won it with. **Inputs** - Player (`person_id`, text, required): The player's id. Search for players returns one per match, and it is also the number in an MLB player page URL. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "awards": [ { "date": "2024-11-21", "id": "ALMVP", "name": "AL Most Valuable Player", "player": { "id": 592450, "nameFirstLast": "Aaron Judge" }, "season": "2024", "team": { "id": 147, "name": "New York Yankees" } } ], "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt" } ``` ### List a team's affiliates List the whole organisation behind a team: its major league club and every minor league affiliate from Triple-A down, each with its own team id. **Inputs** - Teams (`team_ids`, list, required): Which teams to read. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Season (`season`, text): Which season to read. Defaults to the current season. - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "teams": [ { "abbreviation": "NYY", "active": true, "division": { "id": 201, "link": "/api/v1/divisions/201", "name": "American League East" }, "firstYearOfPlay": "1903", "id": 147, "league": { "id": 103, "link": "/api/v1/league/103", "name": "American League" }, "link": "/api/v1/teams/147", "locationName": "Bronx", "name": "New York Yankees", "sport": { "id": 1, "link": "/api/v1/sports/1", "name": "Major League Baseball" }, "teamCode": "nya", "teamName": "Yankees", "venue": { "id": 3313, "link": "/api/v1/venues/3313", "name": "Yankee Stadium" } }, { "abbreviation": "NYY", "active": true, "division": { "id": 201, "link": "/api/v1/divisions/201", "name": "American League East" }, "firstYearOfPlay": "1903", "id": 531, "league": { "id": 103, "link": "/api/v1/league/103", "name": "American League" }, "link": "/api/v1/teams/147", "locationName": "Bronx", "name": "Scranton/Wilkes-Barre RailRiders", "sport": { "id": 11, "name": "Triple-A" }, "teamCode": "nya", "teamName": "Yankees", "venue": { "id": 3313, "link": "/api/v1/venues/3313", "name": "Yankee Stadium" } } ] } ``` ### List a team's alumni List every player who appeared for a team in a season, which is broader than a roster: it includes everyone who came through on a call-up or a short stint. **Inputs** - Team (`team_id`, text, required): Which team to read. - Season (`season`, text, required): Which season to read. - Stat group (`group`, text, required): Which side of the game to list alumni for: hitters, pitchers, and so on. One of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. Default: `hitting`. - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "people": [ { "active": true, "batSide": { "code": "L", "description": "Left" }, "birthCountry": "Japan", "birthDate": "1994-07-05", "currentAge": 31, "firstName": "Shohei", "fullName": "Shohei Ohtani", "height": "6' 4\"", "id": 660271, "lastName": "Ohtani", "link": "/api/v1/people/660271", "mlbDebutDate": "2018-03-29", "pitchHand": { "code": "R", "description": "Right" }, "primaryNumber": "17", "primaryPosition": { "abbreviation": "TWP", "code": "Y", "name": "Two-Way Player", "type": "Two-Way Player" }, "weight": 210 } ] } ``` ### List a team's coaches List a team's coaching staff (manager, bench, hitting and pitching coaches and the rest) with each person's job title. **Inputs** - Team (`team_id`, text, required): Which team to read. - Season (`season`, text): Which season to read. Defaults to the current season. - Date (`date`, date): A single date to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "roster": [ { "jerseyNumber": "17", "job": "Manager", "jobId": "MNGR", "person": { "fullName": "Aaron Boone", "id": 543294 }, "title": "Manager" } ] } ``` ### List a team's history List a franchise's history season by season: the names, cities, leagues and divisions it has played under, so a workflow can resolve what a club was called in a given year. **Inputs** - Teams (`team_ids`, list, required): Which teams to read. - From season (`start_season`, text): Only include seasons from this year onwards. - To season (`end_season`, text): Only include seasons up to this year. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "teams": [ { "abbreviation": "NYY", "active": true, "division": { "id": 201, "link": "/api/v1/divisions/201", "name": "American League East" }, "firstYearOfPlay": "1903", "id": 147, "league": { "id": 103, "link": "/api/v1/league/103", "name": "American League" }, "link": "/api/v1/teams/147", "locationName": "Bronx", "name": "New York Yankees", "season": 1913, "sport": { "id": 1, "link": "/api/v1/sports/1", "name": "Major League Baseball" }, "teamCode": "nya", "teamName": "Yankees", "venue": { "id": 3313, "link": "/api/v1/venues/3313", "name": "Yankee Stadium" } } ] } ``` ### List a team's personnel List a team's non-coaching personnel: the front office, trainers and support staff, each with their job title. **Inputs** - Team (`team_id`, text, required): Which team to read. - Season (`season`, text): Which season to read. Defaults to the current season. - Date (`date`, date): A single date to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "roster": [ { "job": "General Manager", "jobId": "GM", "person": { "fullName": "Brian Cashman", "id": 121234 }, "title": "Senior Vice President, General Manager" } ] } ``` ### List all players at a level List every player at one level of baseball for a season: the whole of MLB in a single call, which is the quickest way to build a local player table. **Inputs** - Sport level (`sport_id`, text, required): Which level of baseball to read. Default: `1`. - Season (`season`, text, required): Which season to read. - Game type (`game_type`, text): Only count games of this type. Leave blank to include every type. One of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "people": [ { "active": true, "batSide": { "code": "L", "description": "Left" }, "birthCountry": "Japan", "birthDate": "1994-07-05", "currentAge": 31, "firstName": "Shohei", "fullName": "Shohei Ohtani", "height": "6' 4\"", "id": 660271, "lastName": "Ohtani", "link": "/api/v1/people/660271", "mlbDebutDate": "2018-03-29", "pitchHand": { "code": "R", "description": "Right" }, "primaryNumber": "17", "primaryPosition": { "abbreviation": "TWP", "code": "Y", "name": "Two-Way Player", "type": "Two-Way Player" }, "weight": 210 } ] } ``` ### List award recipients List who has won an award, with the season and the team they won it with. Name a season for one year's winner, or leave it blank for the whole roll of honour. **Inputs** - Award (`award_id`, text, required): Which award to list the winners of. - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Leagues (`league_ids`, list): Only return results for these leagues. Leave blank for all leagues. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "awards": [ { "date": "2024-11-21", "id": "ALMVP", "name": "AL Most Valuable Player", "player": { "id": 592450, "nameFirstLast": "Aaron Judge" }, "season": "2024", "team": { "id": 147, "name": "New York Yankees" } } ], "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt" } ``` ### List awards List every award the API tracks (the MVPs, Cy Youngs, Gold Gloves, the Hall of Fame and each club's retired numbers) with the id you feed to the other award actions. **Inputs** - Organizations (`org_id`, list): Only return awards given by these organizations. Leave blank for all of them. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "awards": [ { "id": "ALMVP", "name": "AL Most Valuable Player", "notes": "American League", "sortOrder": 1 } ], "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt" } ``` ### List ballparks List the ballparks the API knows, or read one by id. Ask for extra data to get its location, capacity, field dimensions, roof type and timezone. **Inputs** - Ballpark (`venue_id`, text): Read just this ballpark. Leave blank to list them all. - Sport levels (`sport_ids`, list): Only return results from these levels of baseball. - Season (`season`, text): Which season to read. Defaults to the current season. - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "venues": [ { "active": true, "id": 3313, "link": "/api/v1/venues/3313", "location": { "city": "Bronx", "country": "USA", "state": "New York" }, "name": "Yankee Stadium" } ] } ``` ### List changed games List the games whose data MLB has touched since a moment you give it (a rescheduled start, a corrected score, a scoring change). Use it to keep a local copy of the schedule in step without re-reading every game. **Inputs** - Changed since (`updated_since`, date and time, required): Only return games changed after this moment. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "dates": [ { "date": "2025-09-01", "games": [ { "gameDate": "2025-09-01T17:10:00Z", "gameGuid": "d1b0a9c4-3d5f-4a2b-9a41-2f2b7d4c1a55", "gamePk": 776501, "gameType": "R", "link": "/api/v1/game/776501/feed/live", "officialDate": "2025-09-01", "season": "2025", "status": { "abstractGameState": "Final", "codedGameState": "F", "detailedState": "Final", "statusCode": "F" }, "teams": { "away": { "isWinner": true, "score": 4, "team": { "id": 121, "name": "New York Mets" } }, "home": { "isWinner": false, "score": 2, "team": { "id": 116, "name": "Detroit Tigers" } } }, "venue": { "id": 2394, "name": "Comerica Park" } } ], "totalGames": 1 } ], "totalGames": 1, "totalItems": 1 } ``` ### List changed players List the players whose records MLB has touched since a moment you give it, so a local copy of the player database can be kept in step without re-reading all of it. **Inputs** - Changed since (`updated_since`, date and time, required): Only return players changed after this moment. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "people": [ { "fullName": "Shohei Ohtani", "id": 660271 } ] } ``` ### List conferences List the conferences some minor leagues are organised into above the division level. Name a conference to read just that one. **Inputs** - Conference ID (`conference_id`, text): Read just this conference. Leave blank to list them all. - Include inactive conferences (`include_inactive`, true/false): On, conferences no longer in use are included. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "conferences": [ { "abbreviation": "PCLA", "hasWildcard": false, "id": 301, "league": { "id": 112, "link": "/api/v1/league/112" }, "name": "PCL American Conference" } ], "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt" } ``` ### List datacasters List the datacasters: the people who score games into the Stats API from the ballpark. **Inputs** - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Date (`date`, date): A single date to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "roster": [ { "job": "Datacaster", "jobId": "DTCS", "person": { "fullName": "Datacaster", "id": 592789 } } ] } ``` ### List divisions List the divisions in a league or sport level, each with its id, abbreviation and the league it belongs to. Name a division to read just that one. **Inputs** - Division (`division_id`, text): Read just this division. Leave blank to list them all. - League (`league_id`, text): Only return results for this league. Leave blank for all leagues. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Season (`season`, text): Which season to read. Defaults to the current season. - Include inactive divisions (`include_inactive`, true/false): On, divisions no longer in use are included. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "divisions": [ { "abbreviation": "ALE", "hasWildcard": true, "id": 201, "league": { "id": 103, "link": "/api/v1/league/103" }, "name": "American League East", "nameShort": "AL East", "sport": { "id": 1, "link": "/api/v1/sports/1" } } ] } ``` ### List draft picks List the players taken in a draft year, with the round and pick number, the team, the school and the signing bonus. Filter to one team, one round or one player. **Inputs** - Draft year (`year`, text, required): Which draft to read. - Round (`round_number`, text): Only return this round. Leave blank for every round. - Team (`team_id`, text): Only return results for this team. Leave blank for all teams. - Player (`player_id`, text): Only return this player's pick. - Name starts with (`name`, text): Only return players whose name starts with this letter. - School starts with (`school`, text): Only return players whose school starts with this letter. - State (`state`, text): Only return players from this state. - Country (`country`, text): Only return players from this country. - Position (`position`, text): Only return players at this position. One of: `1` (Pitcher (P)), `2` (Catcher (C)), `3` (First base (1B)), `4` (Second base (2B)), `5` (Third base (3B)), `6` (Shortstop (SS)), `7` (Left field (LF)), `8` (Center field (CF)), `9` (Right field (RF)), `10` (Designated hitter (DH)), and 18 more. - Drafted only (`drafted`, true/false): On, only players who were actually taken are returned. - Sort direction (`order`, text): Whether to list the highest or the lowest values first. One of: `desc` (Highest first), `asc` (Lowest first). - Sort by field (`sort_by`, text): Which field to sort the picks by, such as pickNumber. - Number of results (`limit`, number): How many rows to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`. - Rows to skip (`offset`, number): How many rows to skip before returning results. Use it with the number of results to page through a long list (0, then 50, then 100, ...). From 0 to 1000000. Default: `0`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "drafts": { "draftYear": 2024, "rounds": [ { "picks": [ { "bisPlayerId": 831142, "isDrafted": true, "isPass": false, "person": { "fullName": "Travis Bazzana", "id": 700123, "primaryPosition": { "abbreviation": "2B" } }, "pickNumber": 1, "pickRound": "1", "pickValue": "10570600", "rank": 1, "roundPickNumber": 1, "school": { "country": "USA", "name": "Oregon State University", "state": "OR" }, "signingBonus": "9200000", "team": { "id": 114, "name": "Cleveland Guardians" } } ], "round": "1" } ] } } ``` ### List draft prospects List the prospects eligible for a draft, ranked, with their position, school and home state: the board before the picks are made. **Inputs** - Draft year (`year`, text, required): Which draft's prospects to read. - Round (`round_number`, text): Only return prospects tied to this round. - Team (`team_id`, text): Only return results for this team. Leave blank for all teams. - Name starts with (`name`, text): Only return prospects whose name starts with this letter. - School starts with (`school`, text): Only return prospects whose school starts with this letter. - State (`state`, text): Only return prospects from this state. - Country (`country`, text): Only return prospects from this country. - Position (`position`, text): Only return prospects at this position. One of: `1` (Pitcher (P)), `2` (Catcher (C)), `3` (First base (1B)), `4` (Second base (2B)), `5` (Third base (3B)), `6` (Shortstop (SS)), `7` (Left field (LF)), `8` (Center field (CF)), `9` (Right field (RF)), `10` (Designated hitter (DH)), and 18 more. - Drafted only (`drafted`, true/false): On, only prospects who have since been drafted are returned. - Sort direction (`order`, text): Whether to list the highest or the lowest values first. One of: `desc` (Highest first), `asc` (Lowest first). - Sort by field (`sort_by`, text): Which field to sort the prospects by. - Number of results (`limit`, number): How many rows to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`. - Rows to skip (`offset`, number): How many rows to skip before returning results. Use it with the number of results to page through a long list (0, then 50, then 100, ...). From 0 to 1000000. Default: `0`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "offset": 0, "prospects": [ { "bisPlayerId": 831142, "isDrafted": false, "isPass": false, "person": { "fullName": "Travis Bazzana", "id": 700123, "primaryPosition": { "abbreviation": "2B" } }, "pickNumber": 1, "pickRound": "1", "pickValue": "10570600", "rank": 1, "roundPickNumber": 1, "school": { "country": "USA", "name": "Oregon State University", "state": "OR" }, "signingBonus": "9200000", "team": { "id": 114, "name": "Cleveland Guardians" } } ], "queriedSize": 2654, "returnedSize": 1, "totalSize": 0 } ``` ### List free agents List a season's free agents, each with the team they left, the team they signed with, and the date they signed. **Inputs** - Season (`season`, text, required): Which season to read. - Sort direction (`order`, text): Whether to list the highest or the lowest values first. One of: `desc` (Highest first), `asc` (Lowest first). - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "freeAgents": [ { "dateSigned": "2023-12-11", "newTeam": { "id": 119, "name": "Los Angeles Dodgers" }, "originalTeam": { "id": 108, "name": "Los Angeles Angels" }, "player": { "fullName": "Shohei Ohtani", "id": 660271 }, "season": "2024" } ] } ``` ### List leagues List the leagues at a level of baseball, each with its season dates, whether it uses a designated hitter, and its league id. **Inputs** - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - Season (`season`, text): Which season to read. Defaults to the current season. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "leagues": [ { "abbreviation": "AL", "hasWildCard": true, "id": 103, "name": "American League", "nameShort": "American", "numGames": 162, "seasonState": "inseason", "sport": { "id": 1, "link": "/api/v1/sports/1" } } ] } ``` ### List milestones List the career milestones players are approaching or have just reached: the 3,000th hit, the 500th home run, the 300th win. Filter to pending ones to know what is worth watching tonight. **Inputs** - Players (`player_ids`, list): Only return milestones for these players. - Teams (`team_ids`, list): Only return results for these teams. Leave blank for all teams. - Leagues (`league_ids`, list): Only return results for these leagues. Leave blank for all leagues. - Ballparks (`venue_ids`, list): Only return results played at these ballparks. - Games (`game_pks`, list): Only return milestones tied to these games. - Season (`season`, text): Which season to read. Defaults to the current season. - Seasons (`seasons`, list): Which seasons to read. Leave blank for the current season. - Stat group (`stat_group`, text): Only return milestones in this stat group. One of: `hitting`, `pitching`, `fielding`, `catching`, `running`, `game`, `team`, `streak`. - Level (`org_type`, text): Whether to read milestones at team, league or sport level. One of: `T` (Team), `L` (League), `S` (Sport). - Status (`achievement_statuses`, list): Whether to return milestones already achieved, tied, or still pending. One or more of: `A` (Achieved), `T` (Tied), `P` (Pending). - Milestone types (`milestone_types`, list): Cumulative milestones (a career total) or top-N ones (a place on an all-time list). One or more of: `C` (Cumulative), `T` (Top N). - Milestone values (`milestone_values`, list): Only return milestones at these round numbers, such as 500 or 3000. - Hide surpassed milestones (`is_last_achievement`, true/false): On, milestones a player has already gone past are left out. - Number of results (`limit`, number): How many rows to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "milestones": [ { "achievementStatusCode": "P", "currentValue": 296, "milestoneTypeCode": "C", "milestoneValue": 300, "player": { "fullName": "Aaron Judge", "id": 592450 }, "statisticText": "b_home_run" } ] } ``` ### List official scorers List the official scorers: the people who rule on hits and errors. **Inputs** - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Date (`date`, date): A single date to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "roster": [ { "job": "Official Scorer", "jobId": "OSCR", "person": { "fullName": "Official Scorer", "id": 592790 } } ] } ``` ### List people by job List the people holding a job across baseball: any of the API's job types, from umpires and scouts to broadcasters and front-office roles. **Inputs** - Job (`job_type`, text, required): Which job to list the holders of. - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Date (`date`, date): A single date to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "roster": [ { "jerseyNumber": "23", "job": "Umpire", "jobId": "UMPR", "person": { "fullName": "Lance Barksdale", "id": 427146 }, "title": "Umpire" } ] } ``` ### List seasons Get a season's key dates: when the regular season and postseason start and end, and how many games are scheduled. Returns the current season by default, one past season if you name it, or every season back to 1876. **Inputs** - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - League (`league_id`, text): Only return results for this league. Leave blank for all leagues. - Season (`season`, text): Read one past season. Leave blank for the current one. - Every season (`all_seasons`, true/false): On, every season in the API's history is returned and the season above is ignored. Default: `false`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "seasons": [ { "postSeasonEndDate": "2025-11-01", "postSeasonStartDate": "2025-09-30", "regularSeasonEndDate": "2025-09-28", "regularSeasonStartDate": "2025-03-27", "seasonEndDate": "2025-11-01", "seasonId": "2025", "seasonStartDate": "2025-02-20" } ] } ``` ### List sport levels List every level of baseball the API covers (Major League Baseball, each rung of the minors, winter, independent, college, high school, international, Olympic and Negro League Baseball), each with the id the other actions take. **Inputs** - Sport level (`sport_id`, text): Read just this level. Leave blank to list them all. - Season (`season`, text): Which season to read. Defaults to the current season. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "sports": [ { "abbreviation": "MLB", "activeStatus": true, "code": "mlb", "id": 1, "link": "/api/v1/sports/1", "name": "Major League Baseball", "sortOrder": 11 } ] } ``` ### List teams List teams with their names, abbreviations, home ballpark, league, division and first year of play. Narrow it to a sport level, a league or a division, or leave the sport level blank to get every affiliate MLB tracks. **Inputs** - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - Leagues (`league_ids`, list): Only return results for these leagues. Leave blank for all leagues. - Division (`division_id`, text): Only return results for this division. Leave blank for all divisions. - Season (`season`, text): Which season to read. Defaults to the current season. - Game type (`game_type`, text): Only count games of this type. Leave blank to include every type. One of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Active status (`active_status`, text): Whether to include only currently active teams, only inactive ones, or all of them. One of: `Y` (Active only), `N` (Inactive only), `P` (Pending only), `B` (All teams). - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "teams": [ { "abbreviation": "NYY", "active": true, "division": { "id": 201, "link": "/api/v1/divisions/201", "name": "American League East" }, "firstYearOfPlay": "1903", "id": 147, "league": { "id": 103, "link": "/api/v1/league/103", "name": "American League" }, "link": "/api/v1/teams/147", "locationName": "Bronx", "name": "New York Yankees", "sport": { "id": 1, "link": "/api/v1/sports/1", "name": "Major League Baseball" }, "teamCode": "nya", "teamName": "Yankees", "venue": { "id": 3313, "link": "/api/v1/venues/3313", "name": "Yankee Stadium" } } ] } ``` ### List tied games List the games that ended level. Returns an empty list for seasons that had none, so a workflow can branch on the count. **Inputs** - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Which level of baseball to read. Major League Baseball is the default; the same data exists for the minors, winter leagues, college, international and Negro League Baseball. Default: `1`. - Game types (`game_types`, list): Only include games of these types. Leave blank to include every type. One or more of: `R` (Regular Season), `S` (Spring Training), `F` (Wild Card), `D` (Division Series), `L` (League Championship Series), `W` (World Series), `C` (Championship), `P` (Postseason), `A` (All-Star Game), `I` (Intrasquad), `E` (Exhibition). - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "dates": [], "totalItems": 0 } ``` ### List transactions List roster moves (trades, signings, call-ups, options, injured list placements and releases), each with a plain English description. Choose a date or a date range, then narrow to a team, a player or a kind of move. **Inputs** - Date (`date`, date): A single date to read. - Start date (`start_date`, date): First date to include. Use it together with the end date. - End date (`end_date`, date): Last date to include. Use it together with the start date. - Teams (`team_ids`, list): Only return results for these teams. Leave blank for all teams. - Players (`player_id`, list): Only return moves involving these players. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Leagues (`league_ids`, list): Only return results for these leagues. Leave blank for all leagues. - Divisions (`division_ids`, list): Only return moves by teams in these divisions. - Move types (`transaction_types`, list): Only return these kinds of move. Leave blank for all of them. One or more of: `TR` (Trade), `SGN` (Signed), `SFA` (Signed as free agent), `IFA` (Signed as international free agent), `REL` (Released), `URL` (Unconditional release), `DFA` (Declared free agency), `DES` (Designated for assignment), `OPT` (Optioned), `OUT` (Outrighted), and 31 more. - Sort direction (`order`, text): Whether to list the highest or the lowest values first. One of: `desc` (Highest first), `asc` (Lowest first). - Number of results (`limit`, number): How many rows to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`. - Extra data to include (`hydrate`, text): Optional: pull related records into the same response instead of making a second call. Comma-separate several, and nest with parentheses. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "transactions": [ { "date": "2024-07-05", "description": "New York Yankees activated CF Aaron Judge.", "effectiveDate": "2024-07-05", "id": 495863, "person": { "fullName": "Aaron Judge", "id": 592450 }, "team": { "id": 147, "name": "New York Yankees" }, "typeCode": "SC", "typeDesc": "Status Change" } ] } ``` ### List umpires List the umpires on staff, with their uniform numbers. **Inputs** - Season (`season`, text): Which season to read. Defaults to the current season. - Sport level (`sport_id`, text): Only return results from this level of baseball. Leave blank for all levels. - Date (`date`, date): A single date to read. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "roster": [ { "jerseyNumber": "23", "job": "Umpire", "jobId": "UMPR", "person": { "fullName": "Lance Barksdale", "id": 427146 } } ] } ``` ### Look up reference values Read any of the API's own lookup lists straight from MLB: the game types, stat groups and stat types, positions, pitch types and codes, event types, situation codes, roster and standings types, job types, replay review reasons, rule settings, and the rest. Use it when a workflow needs the current codes rather than hard-coded ones. **Inputs** - Reference list (`reference_list`, text, required): Which lookup list to read. One of: `baseballStats` (Baseball stats), `coachingVideoTypes` (Coaching video types), `eventStatus` (Event statuses), `eventTypes` (Event types), `fielderDetailTypes` (Fielder detail types), `gameStatus` (Game statuses), `gameTypes` (Game types), `gamedayTypes` (Gameday types), `groupByTypes` (Group-by types), `highLow/types` (High/low stat types), and 40 more. **Outputs** - `groups` (object) - `list` (text) - `values` (list) **Example output** ```json { "groups": {}, "list": "gameTypes", "values": [ { "description": "Regular Season", "id": "R" }, { "description": "Spring Training", "id": "S" }, { "description": "Postseason", "id": "P" } ] } ``` ### Search for players Find players by name and get their ids back, the usual first step when all you have is a name. Narrow the search to a sport level, a league, a team, a season, or to active players only. **Inputs** - Names (`names`, list): Names to search for. A partial name matches, so "Judge" finds Aaron Judge. - Player IDs (`person_ids`, list): Look players up by id instead of by name. Provide names or ids, at least one of the two. - Sport levels (`sport_ids`, list): Only return results from these levels of baseball. - Leagues (`league_ids`, list): Only return results for these leagues. Leave blank for all leagues. - Teams (`team_ids`, list): Only return results for these teams. Leave blank for all teams. - Seasons (`seasons`, list): Which seasons to read. Leave blank for the current season. - Active players only (`active`, true/false): On, only currently active players are returned. - Rookies only (`rookie`, true/false): On, only rookies are returned. - Verified records only (`verified`, true/false): On, only players whose biographical data MLB has confirmed are returned. - Number of results (`limit`, number): How many rows to return, from 1 to 1000. Defaults to 50. From 1 to 1000. Default: `50`. - Fields to keep (`fields`, list): Optional: return only these fields instead of the whole record, which keeps a large response manageable. Name each level of the path. **Outputs**: None. **Example output** ```json { "copyright": "Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted here http://gdx.mlb.com/components/copyright.txt", "people": [ { "active": true, "batSide": { "code": "L", "description": "Left" }, "birthCountry": "Japan", "birthDate": "1994-07-05", "currentAge": 31, "firstName": "Shohei", "fullName": "Shohei Ohtani", "height": "6' 4\"", "id": 660271, "lastName": "Ohtani", "link": "/api/v1/people/660271", "mlbDebutDate": "2018-03-29", "pitchHand": { "code": "R", "description": "Right" }, "primaryNumber": "17", "primaryPosition": { "abbreviation": "TWP", "code": "Y", "name": "Two-Way Player", "type": "Two-Way Player" }, "weight": 210 } ] } ```