Sport Event Timeline

Time	Status	User Agent
Retrieving recent requests…

⏱️
Update Frequency
TTL / Cache: 1 second
Data Updates: Events land pitch by pitch during play, then stop at the final out
Recommended polling cadences for every feed are on the Update Frequencies chart of the Global Baseball Integration Guide.

📘
Tracking Live Games
Learn how to use the Sport Event Timeline feed to retrieve a game's pitch-by-pitch events in our Tracking Live Games integration scenario.

Data Points

Category & Sport

Attribute	Parent Element	Type	Description
`country_code`	`sport_event_context` - `category`	String	Country code for a sport event's category ex. `JPN` (Japan)
`id`	`sport_event_context` - `category`	String	Unique category ID for a sport event's ex. `sr:category:211`
`name`	`sport_event_context` - `category`	String	Name for a sport event's category ex. `Japan`
`id`	`competitor_profile` - `sport`	String	Unique sport ID for a competitor ex. `sr:sport:3`
`name`	`competitor_profile` - `sport`	String	Name for a competitor's sport ex. `Baseball`

Competition

Attribute	Parent Element	Type	Description
`gender`	`sport_event_context` - `competition`	String	Gender for a sport event `men`, `women`
`id`	`sport_event_context` - `competition`	String	Unique ID for a sport event ex. `sr:competition:1036` (NPB)
`name`	`sport_event_context` - `competition`	String	Name of a competition ex. `NPB`, `Italian Baseball League`
`parent_id`	`sport_event_context` - `competition`	String	Unique parent ID for a competition. Typically present for group competitions ex. `sr:competition:37221` used to group NCAA tournaments.

Groups

Attribute	Parent Element	Type	Description
`id`	`sport_event_context` - `groups` - `group`	String	Unique ID for a sport event's group ex. `sr:league:80925` (National League West)
`name`	`sport_event_context` - `groups` - `group`	String	Name of a sport event's group ex. `MLB 2024, National League West`
`group_name`	`sport_event_context` - `groups` - `group`	String	Abbreviated name of a sport event's group ex. `National League West`

Rounds

Attribute	Parent Element	Type	Description
`competition_sport_event_number`	`sport_event_context` - `round`	Integer	Sport event number within a competition. Used for competitions that have fixed match numbers.
`cup_round_id`	`sport_event_context` - `round`	String	Unique ID for a sport event's cup round ex. `sr:cup_round:1988995`
`cup_round_number_of_sport_events`	`sport_event_context` - `round`	Integer	Number of events in a sport event's round
`cup_round_sport_event_number`	`sport_event_context` - `round`	Integer	Number within the `cup_round` of a match ID. For example, 1st leg of 2
`name`	`sport_event_context` - `round`	String	Name of a sport event's round ex. `quarterfinal` or `final`
`number`	`sport_event_context` - `round`	Integer	Number of a sport event's round
`other_sport_event_id`	`sport_event_context` - `round`	String	A linked sport event ID, typically in a two-legged tie ex. `sr:sport_event:47395897`

Seasons

Attribute	Parent Element	Type	Description
`competition_id`	`sport_event_context` - `season`	String	Unique ID for the competition a sport event belongs to ex. `sr:competition:1036` (NPB 2024)
`disabled`	`sport_event_context` - `season`	Boolean	Signifies a season has been disabled when `true`
`end_date`	`sport_event_context` - `season`	Date	End date of a sport event's season ex. `2024-11-03`
`id`	`sport_event_context` - `season`	String	Unique ID for a sport event's season ex. `sr:season:99979` (World Baseball Classic 2023)
`name`	`sport_event_context` - `season`	String	Name of a sport event's season ex. `NPB 2024`
`start_date`	`sport_event_context` - `season`	Date	Start date of a sport event's season ex. `2024-03-29`
`year`	`sport_event_context` - `season`	String	Year of a sport event's season ex. `23/24` or `2024`

Stages

Attribute	Parent Element	Type	Description
`end_date`	`sport_event_context` - `stage`	Date	End date of a sport event's stage ex. `2024-10-01`
`order`	`sport_event_context` - `stage`	Integer	Order of a stage within a season
`phase`	`sport_event_context` - `stage`	String	Name of a sport event's stage ex. `regular season`, `conference`, `playoffs` See the enum_phase entry in our Global Baseball OpenAPI spec for a complete list of valid `phase` enum values
`start_date`	`sport_event_context` - `stage`	Date	Start date of a sport event's stage ex. `2024-03-20`
`type`	`sport_event_context` - `stage`	String	Type of a sport event's stage `cup`, `league`
`year`	`sport_event_context` - `stage`	String	Year of a sport event's stage ex. `23/24` or `2024`

Competitor

Attribute	Parent Element	Type	Description
`abbreviation`	`competitors` - `competitor`	String	Abbreviation for a competitor name ex. `LAD` (Los Angeles Dodgers)
`age_group`	`competitors` - `competitor`	String	Age group of a competitor, when applicable ex. `U23`
`country`	`competitors` - `competitor`	String	Country of a competitor ex. `Japan`
`country_code`	`competitors` - `competitor`	String	Country code of a competitor ex. `JPN` (Japan)
`gender`	`competitors` - `competitor`	String	Gender for a competitor `male`, `female`
`id`	`competitors` - `competitor`	String	Unique ID for a competitor ex. `sr:competitor:3638` (Los Angeles Dodgers)
`name`	`competitors` - `competitor`	String	Name for a competitor ex. `Los Angeles Dodgers`
`qualifier`	`competitors` - `competitor`	String	Designation of a competitor for a sport event `home`, `away`
`virtual`	`competitors` - `competitor`	Boolean	Signifies a competitor is a virtual team when `true`. Used for placeholder teams in TBD vs TBD matchups.

Coverage Properties

Attribute	Parent Element	Type	Description
`type`	`sport_event` - `coverage`	String	Type of coverage for a sport event `sport_event`, `competition`
`basic_play_by_play`	`sport_event` - `coverage` - `sport_event_properties`	Boolean	Signifies basic play-by-play of a sport event is available when `true`
`scores`	`sport_event` - `coverage` - `sport_event_properties`	Strings	Indicates when sport event scores are made available `live`, `post` (Postgame)

Sport Event

Attribute	Parent Element	Type	Description
`neutral`	`sport_event_conditions` - `ground`	Boolean	Signifies a neutral ground sport event when `true`
`id`	`sport_event`	String	Unique ID of a sport event ex. `sr:sport_event:49796317`
`replaced_by`	`sport_event`	String	An alternative sport event ID if the match is postponed and played at a later date ex. `sr:sport_event:47395897`
`resume_time`	`sport_event`	Date	An updated timestamp if there is a delay at the start or interruption during a match ex. `2024-03-26T20:00:00+00:00`
`start_time`	`sport_event`	Date	Start time of a sport event ex. `2024-03-26T20:00:00+00:00`
`start_time_confirmed`	`sport_event`	Boolean	Signifies the start time of a sport event is confirmed when `true`

Period Scores

Attribute	Parent Element	Type	Description
`away_score`	`sport_event_status` - `period_scores` - `period_score`	Integer	Away team inning score
`home_score`	`sport_event_status` - `period_scores` - `period_score`	Integer	Home team inning score
`number`	`sport_event_status` - `period_scores` - `period_score`	Integer	Inning number
`type`	`sport_event_status` - `period_scores` - `period_score`	String	Inning type `started`, `overtime`, `overtime_break`, `break`, `interrupted`, `1st_inning`, `2nd_inning`, `3rd_inning`, `4th_inning`, `5th_inning`, `6th_inning`, `7th_inning`, `8th_inning`, `9th_inning`, `regular_period`

Sport Event Status

Attribute	Parent Element	Type	Description
`away_score`	`sport_event_status`	Integer	Total score for the away team in the game
`away_normaltime_score`	`sport_event_status`	Integer	Score for the away team in normal time (9 innings)
`home_score`	`sport_event_status`	Integer	Total score for the home team in the game
`home_normaltime_score`	`sport_event_status`	Integer	Score for the home team in normal time (9 innings)
`decided_inning`	`sport_event_status`	Integer	Final inning number of a game
`match_status`	`sport_event_status`	String	Status within a game (sport event). Provides more detail on the state of a sport event when live than `status` ex. `not_started`, `start_delayed`, `1st_inning`, `postponed` See our FAQ for a complete list of statuses and their definitions.
`scout_abandoned`	`sport_event_status`	Boolean	Signifies a game was abandoned by a scout when `true`
`status`	`sport_event_status`	String	Status of a sport event ex. `not_started`, `live`, `ended`, `closed` See our FAQ for a complete list of statuses and their definitions.
`winner_id`	`sport_event_status`	String	Unique ID of the game winner ex. `sr:competitor:3638`

Game Stats (Team)

Attribute	Parent Element	Type	Description
`at_bats`	`competitor` - `statistics`	Integer	Number of at bats for a team in a game
`earned_runs`	`competitor` - `statistics`	Integer	Number of earned runs allowed for a team in a game
`errors`	`competitor` - `statistics`	Integer	Number of errors committed by a team in a game
`hits`	`competitor` - `statistics`	Integer	Number of hits for a team in a game
`hits_allowed`	`competitor` - `statistics`	Integer	Number of hits allowed for a team in a game
`home_runs`	`competitor` - `statistics`	Integer	Number of home runs for a team in a game
`innings_pitched`	`competitor` - `statistics`	Integer	Number of innings pitched for a team in a game
`runs`	`competitor` - `statistics`	Integer	Number of runs scored for a team in a game
`runs_batted_in`	`competitor` - `statistics`	Integer	Number of runs batted in (RBIs) for a team in a game
`saves`	`competitor` - `statistics`	Integer	Number of saves for a team in a game
`stolen_bases`	`competitor` - `statistics`	Integer	Number of stolen bases for a team in a game
`walks`	`competitor` - `statistics`	Integer	Number of walks for a team in a game
`walks_allowed`	`competitor` - `statistics`	Integer	Number of walks allowed for a team in a game

Game Stats (Player)

Attribute	Parent Element	Type	Description
`at_bats`	`player` - `statistics`	Integer	Number of at bats for a player in a game
`earned_runs`	`player` - `statistics`	Integer	Number of earned runs allowed for a player in a game
`errors`	`player` - `statistics`	Integer	Number of errors committed by a player in a game
`hits`	`player` - `statistics`	Integer	Number of hits for a player in a game
`hits_allowed`	`player` - `statistics`	Integer	Number of hits allowed for a player in a game
`home_runs`	`player` - `statistics`	Integer	Number of home runs for a player in a game
`innings_pitched`	`player` - `statistics`	Integer	Number of innings pitched for a player in a game
`runs`	`player` - `statistics`	Integer	Number of runs scored for a player in a game
`runs_batted_in`	`player` - `statistics`	Integer	Number of runs batted in (RBIs) for a player in a game
`saves`	`player` - `statistics`	Integer	Number of saves for a player in a game
`stolen_bases`	`player` - `statistics`	Integer	Number of stolen bases for a player in a game
`walks`	`player` - `statistics`	Integer	Number of walks for a player in a game
`walks_allowed`	`player` - `statistics`	Integer	Number of walks allowed for a player in a game

Game Timeline

Attribute	Parent Element	Type	Description
`advancement_type`	`timeline` - `event`	String	Information on how a batter advanced on a play `unknown`, `catcher_interference`, `hit_by_pitch`, `on_error`, `single`, `double`, `triple`, `sacrifice_bunt`, `sacrifice_fly`, `walk`, `fielders_choice`, `other`
`ball_in_play_type`	`timeline` - `event`	String	Indicates, along with `type="ball_in_play`, that a batter struck a ball into play. The following event indicates the outcome of the ball in play.
`base`	`timeline` - `event`	Integer	Base associated with a `runner_check` event type
`count_balls`	`timeline` - `event`	Integer	Number of balls in an at bat, after an event
`count_strikes`	`timeline` - `event`	Integer	Number of strikes in an at bat, after an event
`ending_base`	`timeline` - `event`	Integer	Ending base number for a player after an event
`errors`	`timeline` - `event`	Integer	Number of errors in a play
`id`	`timeline` - `event`	String	Unique Id of a timeline event ex. `2182830584`
`inning`	`timeline` - `event`	Integer	Inning number associated with a timeline event. Typically populates at the end of a full innning along with a `inning_score_update`.
`inning_half`	`timeline` - `event`	String	Indicates the type of inning associated with a timeline event ex. `top`, `bottom`
`inning_away_score`	`timeline` - `event`	Integer	Number of runs scored for the away team in an inning. Typically populates at the end of a full innning along with a `inning_score_update`.
`inning_home_score`	`timeline` - `event`	Integer	Number of runs scored for the home team in an inning. Typically populates at the end of a full innning along with a `inning_score_update`.
`is_out`	`timeline` - `event`	Boolean	Signifies an out was recorded for an event when `true`
`on_base_type`	`timeline` - `event`	String	Method of reaching base for a player. Typically associated with a `player_on_base` event type. ex. `single`, `walk`, `hit_by_pitch` See enum_on_base_type in our Global Baseball spec for a complete list of types
`outcome`	`timeline` - `event`	String	Outcome of an at bat ex. `single`, `double`, `walk`
`out_base`	`timeline` - `event`	Integer	Base number where an out was recorded
`out_type`	`timeline` - `event`	String	Type of out recorded for an event. Typically associated with a `player_out` event type. ex. `strikeout`, `force_out`, `ground_out` See enum_out_type in our Global Baseball spec for a complete list of types
`outs`	`timeline` - `event`	Integer	Number of current outs in an inning
`outs_on_play`	`timeline` - `event`	Integer	Number of outs assocated with an event
`pitch_number`	`timeline` - `event`	Integer	Pitch number of an at bat
`qualifier`	`timeline` - `event`	String	Designation of a competitor for a timeline event. Typically used for a `substitution` event type. `home`, `away`
`result`	`timeline` - `event`	String	Result of a pitch ex. `ball`, `strike`, `foul`
`scored_run_type`	`timeline` - `event`	String	Type of out run for an event. Typically associated with a `run_scored` event type. ex. `strikeout`, `force_out`, `ground_out` See enum_scored_run_type in our Global Baseball spec for a complete list of types
`starting_base`	`timeline` - `event`	Integer	Starting base number for a player after an event
`time`	`timeline` - `event`	Date-time	Timestamp of a timeline event ex. `2024-04-16T20:49:49+00:00`
`type`	`timeline` - `event`	String	Type of timeline event ex. `match_started`, `run_scored`, `player_out`, `substitution`, `strike` See enum_event_type in our Global Baseball spec for a complete list of event types

Player (Timeline Event)

Attribute	Parent Element	Type	Description
`id`	`timeline` - `event` - `player`	String	Unique ID of a player associated with an event ex. `sr:player:1396097`
`name`	`timeline` - `event` - `player`	String	Name of a player associated with an event ex. `Varsho, Daulton`
`type`	`timeline` - `event` - `player`	String	Player type associated with an event ex. `batter`, `pitcher`, `runner`, `substituted_out`, `substituted_in`

Venue

Attribute	Parent Element	Type	Description
`capacity`	`venue`	Integer	Capacity of a venue ex. `56000`
`changed`	`venue`	Boolean	Signifies a venue has been changed when `true`
`city_id`	`venue`	String	Unique ID of a city ex. `sr:city:59`
`city_name`	`venue`	String	City name of a venue ex. `Los Angeles`
`country_code`	`venue`	String	Country code of a venue ex. `USA`
`country_name`	`venue`	String	Country name of a venue ex. `USA`
`id`	`venue`	String	Unique ID of a venue ex. `sr:venue:8117`
`map_coordinates`	`venue`	String	Coordinates of a venue ex. `34.0745409,-118.2408881`
`name`	`venue`	String	Name of a venue ex. `Dodger Stadium`
`reduced_capacity`	`venue`	Boolean	Optional attribute signifying a venue has a restricted capacity when `true`
`reduced_capacity_max`	`venue`	Integer	Value of a venue's restricted capacity
`timezone`	`venue`	String	Timezone of a venue ex. `America/Los_Angeles`

Update Frequency

Tracking Live Games

Data Points

200200