Skip to main content

MLB — MLB Stats API — Game

mlb_game_context_metrics​

GET /api/v1/game/{gamePk}/contextMetrics — WP, leverage index, in-game context.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/contextMetrics

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/contextMetrics

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_game_context_metrics(game_pk=716390)

mlb_game_content​

GET /api/v1/game/{gamePk}/content — articles, highlights, editorial content.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/content

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/content

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_game_content(game_pk=716390)

mlb_game_timestamps​

Retrieve all of the play timecodes for a game in GUMBO feed.

Endpoint URL: GET https://statsapi.mlb.com/api/v1.1/game/{game_pk}/feed/live/timestamps

Valid URL: https://statsapi.mlb.com/api/v1.1/game/716390/feed/live/timestamps

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
timecodeStringA timestamp string representing a specific point in time used to query the MLB Stats API for game state changes.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_game_timestamps(game_pk=716390)

mlb_game_changes​

View corrected non Statcast information for games

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/changes

Valid URL: https://statsapi.mlb.com/api/v1/game/changes?updatedSince=2023-09-01T00%3A00%3A00Z&sportId=1

API ParameterPythonPatternRequiredNullableDescription
updatedSinceupdated_sinceYupdatedSince query parameter.
sportIdsport_idYsportId query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
schedule_dateStringThe calendar date for which schedule changes are being reported, identifying when rescheduled or suspended games occurred.
game_pkInt64Unique game identifier.
game_guidStringGlobally unique game identifier (GUID).
linkStringAPI link to the game feed.
game_typeStringGame type code (R, P, etc.).
seasonStringSeason year.
game_dateStringGame date (YYYY-MM-DD).
official_dateStringOfficial game date (YYYY-MM-DD).
is_tieBooleanWhether the game ended in a tie.
game_numberInt64Game number within a doubleheader.
public_facingBooleanWhether the game is public-facing.
double_headerStringDoubleheader indicator ('N', 'S', 'Y').
gameday_typeStringGameday data feed type.
tiebreakerStringWhether the game is a tiebreaker.
calendar_event_idStringCalendar event identifier.
season_displayStringDisplay string for the season.
day_nightStringDay or night game indicator.
scheduled_inningsInt64Scheduled number of innings.
reverse_home_away_statusBooleanWhether home/away teams are reversed.
inning_break_lengthInt64Length of inning breaks in seconds.
games_in_seriesFloat64Number of games in the series.
series_game_numberFloat64Game number within the series.
series_descriptionStringDescription of the series.
record_sourceStringSource of the schedule record.
if_necessaryStringWhether the game is played only if necessary.
if_necessary_descriptionStringDescription of the if-necessary status.
status_abstract_game_stateStringAbstract game state (e.g. 'Final').
status_coded_game_stateStringCoded game state.
status_detailed_stateStringDetailed game state.
status_status_codeStringStatus code for the game.
status_start_time_tbdBooleanWhether the start time is TBD.
status_abstract_game_codeStringAbstract game state code.
teams_away_team_idInt64Away team MLBAM ID.
teams_away_team_nameStringAway team name.
teams_away_team_linkStringAPI link to the away team.
teams_away_league_record_winsInt64Away team league-record wins.
teams_away_league_record_lossesInt64Away team league-record losses.
teams_away_league_record_tiesInt64Away team league-record ties.
teams_away_league_record_pctStringAway team winning percentage.
teams_away_scoreInt64Away team score.
teams_away_is_winnerBooleanWhether the away team won.
teams_away_split_squadBooleanWhether the away team is a split squad.
teams_away_series_numberFloat64Away team's series number.
teams_home_team_idInt64Home team MLBAM ID.
teams_home_team_nameStringHome team name.
teams_home_team_linkStringAPI link to the home team.
teams_home_league_record_winsInt64Home team league-record wins.
teams_home_league_record_lossesInt64Home team league-record losses.
teams_home_league_record_tiesInt64Home team league-record ties.
teams_home_league_record_pctStringHome team winning percentage.
teams_home_scoreInt64Home team score.
teams_home_is_winnerBooleanWhether the home team won.
teams_home_split_squadBooleanWhether the home team is a split squad.
teams_home_series_numberFloat64Home team's series number.
venue_idInt64MLBAM venue ID.
venue_nameStringVenue name.
venue_linkStringAPI link to the venue.
content_linkStringAPI link to the game content.
rescheduled_fromStringOriginal date-time the game was rescheduled from.
rescheduled_from_dateStringOriginal date the game was rescheduled from.
descriptionStringLong-form description text.
status_reasonStringReason for the game status (e.g. 'Rain').
resumed_fromStringOriginal date-time if the game was resumed.
resumed_from_dateStringOriginal date if the game was resumed.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_game_changes(sport_id=1, updated_since='2023-09-01T00:00:00Z')

mlb_game_guids​

View Statcast data for a specific game.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/guids

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/guids

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
gameModeIdgame_mode_idYgameModeId query parameter.
updatedSinceupdated_sinceYupdatedSince query parameter.
isPitchis_pitchYisPitch query parameter.
isHitis_hitYisHit query parameter.
isPickoffis_pickoffYisPickoff query parameter.
hydratehydrateYhydrate query parameter.
parsed/rawparsed_rawYparsed/raw query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — the output of parse_mlb_api_list; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: no capture: statsapi.mlb.com answers 406 to the datacenter IP and 401 'Please Login' through the residential proxy; the route needs an MLB login session the package does not hold.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_game_guids(game_pk=716390)

mlb_game_color​

View game color commentary info.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/feed/color

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/feed/color

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
timecodetimecodeYtimecode query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — the output of parse_mlb_api_list; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: no capture: statsapi.mlb.com answers 406 to the datacenter IP and 404 through the residential proxy with the documented example arguments (2026-10-07).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_game_color(game_pk=716390)

mlb_game_color_diff​

View game color feed.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/feed/color/diffPatch

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/feed/color/diffPatch

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
startTimecodestart_timecodeYstartTimecode query parameter.
endTimecodeend_timecodeYendTimecode query parameter.

Returns​

return_parsed=True (default) — the output of parse_mlb_api_list; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: no capture: statsapi.mlb.com answers 406 to the datacenter IP and 404 through the residential proxy with the documented example arguments (2026-10-07).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_game_color_diff(game_pk=716390)

mlb_game_color_timestamps​

View all of the color timecodes for a game.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/feed/color/timestamps

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/feed/color/timestamps

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.

Returns​

return_parsed=True (default) — the output of parse_mlb_api_timecodes; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: no capture: statsapi.mlb.com answers 406 to the datacenter IP and 404 through the residential proxy with the documented example arguments (2026-10-07).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_game_color_timestamps(game_pk=716390)

mlb_game_pace​

View time of game info.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/gamePace

Valid URL: https://statsapi.mlb.com/api/v1/gamePace?season=2023

API ParameterPythonPatternRequiredNullableDescription
seasonseasonYSeason year (e.g. 2024).
teamIdsteam_idsYteamIds query parameter.
leagueIdsleague_idsYleagueIds query parameter.
leagueListIdleague_list_idYleagueListId query parameter.
sportIdsport_idYsportId query parameter.
gameTypegame_typeYgameType query parameter.
startDatestart_dateYstartDate query parameter.
endDateend_dateYendDate query parameter.
venueIdsvenue_idsYvenueIds query parameter.
orgTypeorg_typeYorgType query parameter.
includeChildreninclude_childrenYincludeChildren query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
hits_per9_innFloat64Average number of hits allowed per nine innings across all games in the sample period.
runs_per9_innFloat64Average number of runs scored per nine innings across all games in the sample period.
pitches_per9_innFloat64Average number of pitches thrown per nine innings across all games in the sample period.
plate_appearances_per9_innFloat64Average number of plate appearances occurring per nine innings across all games in the sample period.
hits_per_gameFloat64Hits per game.
runs_per_gameFloat64Runs per game.
innings_played_per_gameFloat64Innings played per game.
pitches_per_gameFloat64Pitches per game.
pitchers_per_gameFloat64Pitchers used per game.
plate_appearances_per_gameFloat64Plate appearances per game.
total_game_timeStringTotal game time (HHH:MM:SS).
total_innings_playedFloat64Total innings played.
total_hitsInt64Total hits.
total_runsInt64Total runs.
total_plate_appearancesInt64Total plate appearances.
total_pitchersInt64Total pitchers used.
total_pitchesInt64Total pitches thrown.
total_gamesInt64Total games on the date.
total7_inn_gamesInt64Total number of seven-inning games played (including doubleheader games).
total9_inn_gamesFloat64Total number of nine-inning games played in the sample period.
total_extra_inn_gamesInt64Total extra-inning games.
time_per_gameStringAverage time per game (HH:MM:SS).
time_per_pitchStringAverage time per pitch (HH:MM:SS).
time_per_hitStringAverage time per hit (HH:MM:SS).
time_per_runStringAverage time per run (HH:MM:SS).
time_per_plate_appearanceStringAverage time per plate appearance (HH:MM:SS).
time_per9_innStringAverage elapsed clock time per nine-inning game formatted as hours and minutes.
time_per77_plate_appearancesStringAverage time per 77 plate appearances, used as a normalized pace benchmark by MLB.
total_extra_inn_timeStringTotal extra-inning time (HHH:MM:SS).
time_per7_inn_game_without_extra_innStringAverage elapsed clock time per seven-inning game excluding games that went to extra innings.
total9_inn_games_completed_earlyInt64Number of nine-inning games that were called or suspended before completing nine full innings.
total9_inn_games_without_extra_innFloat64Number of nine-inning games completed without requiring extra innings.
total9_inn_games_scheduledInt64Total number of nine-inning games that were scheduled in the sample period.
hits_per_runFloat64Hits per run.
pitches_per_pitcherFloat64Pitches per pitcher.
seasonStringSeason year.
sport_idInt64Sport MLBAM ID.
sport_codeStringShort sport code (e.g. 'mlb', 'aaa').
sport_linkStringAPI link to the sport.
pr_portal_calculated_fields_total7_inn_gamesInt64Calculated total count of seven-inning games as tallied by the MLB Stats API pace portal.
pr_portal_calculated_fields_total9_inn_gamesFloat64Calculated total count of nine-inning games as tallied by the MLB Stats API pace portal.
pr_portal_calculated_fields_total_extra_inn_gamesInt64Portal-calculated total extra-inning games.
pr_portal_calculated_fields_time_per7_inn_gameStringCalculated average game time per seven-inning game as produced by the MLB Stats API pace portal.
pr_portal_calculated_fields_time_per9_inn_gameStringCalculated average game time per nine-inning game as produced by the MLB Stats API pace portal.
pr_portal_calculated_fields_time_per_extra_inn_gameStringPortal-calculated time per extra-inning game.
time_per7_inn_gameStringAverage elapsed clock time per seven-inning game formatted as hours and minutes.
total7_inn_games_scheduledFloat64Total number of seven-inning games that were scheduled in the sample period.
total7_inn_games_without_extra_innFloat64Number of seven-inning games completed without requiring extra innings.
total7_inn_games_completed_earlyFloat64Number of seven-inning games that were called or completed before the full seven innings were played.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_game_pace(season='2023')