Match Status Workflow
Intro
Every soccer match progresses through a series of statuses during its lifecycle. Use the status and match_status fields to determine the appropriate endpoint to call at each stage.
Difference Between
statusandmatch_statusThe
statusfield indicates the overall state of the match—before it starts, during live play, and after it ends.Once the match is live, you can use the
match_statusfield to get more detailed sub-statuses that describe the specific phase of the live match (e.g.,halftime,overtime,penalties).
Retrieving status
The status is available in every Schedule endpoint. To retrieve a match's initial status and schedule information it would be most appropriate to request the Season Schedule, Daily Schedules, Competitor Schedulesor Player Schedules endpoints.
<schedule>
<sport_event id="sr:sport_event:50849967" start_time="2024-08-16T19:00:00+00:00" start_time_confirmed="true">
<sport_event_context>
<sport id="sr:sport:1" name="Soccer"/>
<category id="sr:category:1" name="England" country_code="ENG"/>
<competition id="sr:competition:17" name="Premier League" gender="men"/>
<season id="sr:season:118689" name="Premier League 24/25" start_date="2024-08-16" end_date="2025-05-25" year="24/25" competition_id="sr:competition:17"/>
<stage order="1" type="league" phase="regular season" start_date="2024-08-16" end_date="2025-05-25" year="24/25"/>
<round number="1"/>
<groups>
<group id="sr:league:84075" name="Premier League 24/25"/>
</groups>
</sport_event_context>
<coverage type="sport_event">
<sport_event_properties lineups="true" formations="false" venue="true" extended_player_stats="true" extended_team_stats="true" lineups_availability="pre" ballspotting="true" commentary="true" fun_facts="true" goal_scorers="true" goal_scorers_live="true" scores="live" game_clock="true" deeper_play_by_play="true" deeper_player_stats="true" deeper_team_stats="true" basic_play_by_play="true" basic_player_stats="true" basic_team_stats="true"/>
</coverage>
<competitors>
<competitor id="sr:competitor:35" name="Manchester United" country="England" country_code="ENG" abbreviation="MUN" qualifier="home" gender="male"/>
<competitor id="sr:competitor:43" name="Fulham FC" country="England" country_code="ENG" abbreviation="FUL" qualifier="away" gender="male"/>
</competitors>
<venue id="sr:venue:9" name="Old Trafford" capacity="75635" city_name="Manchester" country_name="England" map_coordinates="53.463150,-2.291444" country_code="ENG" timezone="Europe/London"/>
</sport_event>
<sport_event_status status="closed" match_status="ended" home_score="1" away_score="0" winner_id="sr:competitor:35">
<period_scores>
<period_score home_score="0" away_score="0" type="regular_period" number="1"/>
<period_score home_score="1" away_score="0" type="regular_period" number="2"/>
</period_scores>
</sport_event_status>
</schedule>
{
"sport_event": {
"id": "sr:sport_event:50849967",
"start_time": "2024-08-16T19:00:00+00:00",
"start_time_confirmed": true,
"sport_event_context": {
"sport": {
"id": "sr:sport:1",
"name": "Soccer"
},
"category": {
"id": "sr:category:1",
"name": "England",
"country_code": "ENG"
},
"competition": {
"id": "sr:competition:17",
"name": "Premier League",
"gender": "men"
},
"season": {
"id": "sr:season:118689",
"name": "Premier League 24/25",
"start_date": "2024-08-16",
"end_date": "2025-05-25",
"year": "24/25",
"competition_id": "sr:competition:17"
},
"stage": {
"order": 1,
"type": "league",
"phase": "regular season",
"start_date": "2024-08-16",
"end_date": "2025-05-25",
"year": "24/25"
},
"round": {
"number": 1
},
"groups": [
{
"id": "sr:league:84075",
"name": "Premier League 24/25"
}
]
},
"coverage": {
"type": "sport_event",
"sport_event_properties": {
"lineups": true,
"formations": false,
"venue": true,
"extended_player_stats": true,
"extended_team_stats": true,
"lineups_availability": "pre",
"ballspotting": true,
"commentary": true,
"fun_facts": true,
"goal_scorers": true,
"goal_scorers_live": true,
"scores": "live",
"game_clock": true,
"deeper_play_by_play": true,
"deeper_player_stats": true,
"deeper_team_stats": true,
"basic_play_by_play": true,
"basic_player_stats": true,
"basic_team_stats": true
}
},
"competitors": [
{
"id": "sr:competitor:35",
"name": "Manchester United",
"country": "England",
"country_code": "ENG",
"abbreviation": "MUN",
"qualifier": "home",
"gender": "male"
},
{
"id": "sr:competitor:43",
"name": "Fulham FC",
"country": "England",
"country_code": "ENG",
"abbreviation": "FUL",
"qualifier": "away",
"gender": "male"
}
],
"venue": {
"id": "sr:venue:9",
"name": "Old Trafford",
"capacity": 75635,
"city_name": "Manchester",
"country_name": "England",
"map_coordinates": "53.463150,-2.291444",
"country_code": "ENG",
"timezone": "Europe/London"
}
},
"sport_event_status": {
"status": "closed",
"match_status": "ended",
"home_score": 1,
"away_score": 0,
"winner_id": "sr:competitor:35",
"period_scores": [
{
"home_score": 0,
"away_score": 0,
"type": "regular_period",
"number": 1
},
{
"home_score": 1,
"away_score": 0,
"type": "regular_period",
"number": 2
}
]
}
}
Retrieving match status
The match_status field is most useful during live matches and is typically accessed through Event endpoints that also provide live details such as statistics and play-by-play events. To monitor a match's live status, we recommend using the Sport Event Lineups, Sport Event Summary, or Sport Event Timeline endpoints.
<sport_event id="sr:sport_event:51133377" start_time="2025-06-05T18:15:00+00:00" start_time_confirmed="true">
<sport_event_context>
<sport id="sr:sport:1" name="Soccer"/>
<category id="sr:category:4" name="International"/>
<competition id="sr:competition:308" name="World Cup Qualification AFC" parent_id="sr:competition:24660" gender="men"/>
<season id="sr:season:108589" name="World Cup Qualification 2026, AFC" start_date="2023-10-12" end_date="2025-11-25" year="23-25" competition_id="sr:competition:308"/>
<stage order="3" type="league" phase="regular season" start_date="2024-09-05" end_date="2025-06-10" year="23-25"/>
<round number="9"/>
<groups>
<group id="sr:league:76709" name="World Cup 2026, AFC Qualification, Round 3, Group A" group_name="A"/>
</groups>
</sport_event_context>
<coverage type="sport_event">
<sport_event_properties lineups="true" formations="false" venue="true" extended_player_stats="false" extended_team_stats="false" lineups_availability="pre" ballspotting="true" commentary="true" fun_facts="true" goal_scorers="true" goal_scorers_live="true" scores="live" game_clock="true" deeper_play_by_play="true" deeper_player_stats="true" deeper_team_stats="true" basic_play_by_play="true" basic_player_stats="true" basic_team_stats="true"/>
</coverage>
<competitors>
<competitor id="sr:competitor:4792" name="Qatar" country="Qatar" country_code="QAT" abbreviation="QAT" qualifier="home" gender="male"/>
<competitor id="sr:competitor:4766" name="IR Iran" country="Iran" country_code="IRN" abbreviation="IRI" qualifier="away" gender="male"/>
</competitors>
<venue id="sr:venue:2205" name="Jassim Bin Hamad Stadium" capacity="35000" city_name="Doha" country_name="Qatar" map_coordinates="25.267358,51.484251" country_code="QAT" timezone="Asia/Qatar"/>
<sport_event_conditions>
<referees>
<referee id="sr:referee:2162222" name="Khled Hoish, Mohammed" nationality="Saudi Arabia" country_code="SAU" type="main_referee"/>
</referees>
<weather pitch_conditions="good" overall_conditions="medium"/>
<ground neutral="false"/>
<lineups confirmed="true"/>
</sport_event_conditions>
</sport_event>
<sport_event_status status="live" match_status="1st_half" home_score="0" away_score="0">
<period_scores>
<period_score home_score="0" away_score="0" type="regular_period" number="1"/>
</period_scores>
<ball_locations>
<ball_location order="4" x="63" y="81" qualifier="away"/>
<ball_location order="3" x="71" y="76" qualifier="away"/>
<ball_location order="2" x="93" y="62" qualifier="away"/>
<ball_location order="1" x="93" y="62" qualifier="home"/>
</ball_locations>
<match_situation status="safe" qualifier="away" updated_at="2025-06-05T18:35:27+00:00"/>
<clock played="17:16"/>
</sport_event_status>
<statistics>
<totals>
<competitors>
<competitor id="sr:competitor:4792" name="Qatar" abbreviation="QAT" qualifier="home">
<statistics ball_possession="44" cards_given="0" corner_kicks="0" fouls="1" free_kicks="3" goal_kicks="0" injuries="1" offsides="1" red_cards="0" shots_blocked="0" shots_off_target="1" shots_on_target="0" shots_saved="2" shots_total="1" substitutions="0" throw_ins="4" yellow_cards="0" yellow_red_cards="0"/>
<players>
<player id="sr:player:223372" name="Hatem, Abdel Aziz" starter="false">
<statistics assists="0" corner_kicks="0" goals_scored="0" offsides="0" own_goals="0" red_cards="0" shots_blocked="0" shots_off_target="0" shots_on_target="0" substituted_in="0" substituted_out="0" yellow_cards="0" yellow_red_cards="0"/>
</player>
<player id="sr:player:229278" name="Alaaeldin, Ahmed" starter="true">
<statistics assists="0" corner_kicks="0" goals_scored="0" offsides="0" own_goals="0" red_cards="0" shots_blocked="0" shots_off_target="0" shots_on_target="0" substituted_in="0" substituted_out="0" yellow_cards="0" yellow_red_cards="0"/>
</player>
{
"sport_event": {
"id": "sr:sport_event:51133377",
"start_time": "2025-06-05T18:15:00+00:00",
"start_time_confirmed": true,
"sport_event_context": {
"sport": {
"id": "sr:sport:1",
"name": "Soccer"
},
"category": {
"id": "sr:category:4",
"name": "International"
},
"competition": {
"id": "sr:competition:308",
"name": "World Cup Qualification AFC",
"parent_id": "sr:competition:24660",
"gender": "men"
},
"season": {
"id": "sr:season:108589",
"name": "World Cup Qualification 2026, AFC",
"start_date": "2023-10-12",
"end_date": "2025-11-25",
"year": "23-25",
"competition_id": "sr:competition:308"
},
"stage": {
"order": 3,
"type": "league",
"phase": "regular season",
"start_date": "2024-09-05",
"end_date": "2025-06-10",
"year": "23-25"
},
"round": {
"number": 9
},
"groups": [
{
"id": "sr:league:76709",
"name": "World Cup 2026, AFC Qualification, Round 3, Group A",
"group_name": "A"
}
]
},
"coverage": {
"type": "sport_event",
"sport_event_properties": {
"lineups": true,
"formations": false,
"venue": true,
"extended_player_stats": false,
"extended_team_stats": false,
"lineups_availability": "pre",
"ballspotting": true,
"commentary": true,
"fun_facts": true,
"goal_scorers": true,
"goal_scorers_live": true,
"scores": "live",
"game_clock": true,
"deeper_play_by_play": true,
"deeper_player_stats": true,
"deeper_team_stats": true,
"basic_play_by_play": true,
"basic_player_stats": true,
"basic_team_stats": true
}
},
"competitors": [
{
"id": "sr:competitor:4792",
"name": "Qatar",
"country": "Qatar",
"country_code": "QAT",
"abbreviation": "QAT",
"qualifier": "home",
"gender": "male"
},
{
"id": "sr:competitor:4766",
"name": "IR Iran",
"country": "Iran",
"country_code": "IRN",
"abbreviation": "IRI",
"qualifier": "away",
"gender": "male"
}
],
"venue": {
"id": "sr:venue:2205",
"name": "Jassim Bin Hamad Stadium",
"capacity": 35000,
"city_name": "Doha",
"country_name": "Qatar",
"map_coordinates": "25.267358,51.484251",
"country_code": "QAT",
"timezone": "Asia/Qatar"
},
"sport_event_conditions": {
"referees": [
{
"id": "sr:referee:2162222",
"name": "Khled Hoish, Mohammed",
"nationality": "Saudi Arabia",
"country_code": "SAU",
"type": "main_referee"
}
],
"weather": {
"pitch_conditions": "good",
"overall_conditions": "medium"
},
"ground": {
"neutral": false
},
"lineups": {
"confirmed": true
}
}
},
"sport_event_status": {
"status": "live",
"match_status": "1st_half",
"home_score": 0,
"away_score": 0,
"period_scores": [
{
"home_score": 0,
"away_score": 0,
"type": "regular_period",
"number": 1
}
],
"ball_locations": [
{
"order": 4,
"x": 34,
"y": 82,
"qualifier": "away"
},
{
"order": 3,
"x": 61,
"y": 41,
"qualifier": "away"
},
{
"order": 2,
"x": 40,
"y": 21,
"qualifier": "away"
},
{
"order": 1,
"x": 40,
"y": 21,
"qualifier": "home"
}
],
"match_situation": {
"status": "attack",
"qualifier": "away",
"updated_at": "2025-06-05T18:37:30+00:00"
},
"clock": {
"played": "19:14"
}
},
"statistics": {
"totals": {
"competitors": [
{
"id": "sr:competitor:4792",
"name": "Qatar",
"abbreviation": "QAT",
"qualifier": "home",
"statistics": {
"ball_possession": 64,
"cards_given": 0,
"corner_kicks": 0,
"fouls": 1,
"free_kicks": 4,
"goal_kicks": 0,
"injuries": 1,
"offsides": 2,
"red_cards": 0,
"shots_blocked": 0,
"shots_off_target": 1,
"shots_on_target": 0,
"shots_saved": 2,
"shots_total": 1,
"substitutions": 0,
"throw_ins": 4,
"yellow_cards": 0,
"yellow_red_cards": 0
},
"players": [
{
"statistics": {
"assists": 0,
"corner_kicks": 0,
"goals_scored": 0,
"offsides": 0,
"own_goals": 0,
"red_cards": 0,
"shots_blocked": 0,
"shots_off_target": 0,
"shots_on_target": 0,
"substituted_in": 0,
"substituted_out": 0,
"yellow_cards": 0,
"yellow_red_cards": 0
},
"id": "sr:player:223372",
"name": "Hatem, Abdel Aziz",
"starter": false
},
{
"statistics": {
"assists": 0,
"corner_kicks": 0,
"goals_scored": 0,
"offsides": 0,
"own_goals": 0,
"red_cards": 0,
"shots_blocked": 0,
"shots_off_target": 0,
"shots_on_target": 0,
"substituted_in": 0,
"substituted_out": 0,
"yellow_cards": 0,
"yellow_red_cards": 0
},
"id": "sr:player:229278",
"name": "Alaaeldin, Ahmed",
"starter": true
}
]
}
]
}
}
}
Coverage Levels
Tiers
The Soccer API is organized into 9 tiers, with Tier 1 offering the most comprehensive data and Tier 9 the least. Tiers determine the level of detail available for a given competition—such as player transfers, missing players, team squads, and season statistics.
Event Coverage
We offer three standard levels of match coverage across soccer competitions:
- Live Coverage: Includes real-time play-by-play events and statistics for all matches during a season.
- Post-match Coverage: Match results and event data are entered after the match concludes.
- Cup Coverage (Tier 6): Early qualification rounds of cup competitions may receive post-match or limited coverage, while later stages are fully covered with live data.
For more details about competition-level coverage, visit the Coverage Matrix.
Status Definitions
status
Below are each of the overall status values you can expect to see returned from the Soccer API status attribute. Reference these definitions for details on what each sport event state signifies.
not_started– The match is scheduled to be playedstarted- The match has begunlive– The match is currently in progresspostponed– The match has been postponed to a future datesuspended- The match has been suspendeddelayed– The match has been temporarily delayed and will be continued. Typically appears prior to match startinterrupted- The match began, but coverage has stopped for a short time. Note that match scores may not be updated during this period, the last recorded match score will be displayed insteadcancelled– The match has been cancelled and will not be playedended– The match is overclosed– The match results have been confirmedabandoned- The match has been abandoned
match_status
Below are the valid match_status values you may encounter in the Soccer API. Use these definitions to understand the specific phases of a match while it is in a live state.
not_started– The match is scheduled to be playedstarted- The match has begun1st_half– The match is in the first half2nd_half– The match is in the second halfovertime– The match is in overtime1st_extra– The match is in the first extra period2nd_extra– The match is in the second extra periodawaiting_penalties– Waiting for announcement of penaltiespenalties– Penalties are ongoingawaiting_extra_time– Waiting on referee to announce extra timeinterrupted– The match has been interruptedabandoned– The match has been abandonedpostponed– The match has been postponed to a future datestart_delayed– The match has been temporarily delayed and will be continuedcancelled– The match has been cancelled and will not be playedhalftime– The match is in halftimeextra_time_halftime– The match is in extra time halftimeended– The match has endedaet– The match has ended after extra timeap– The match has ended after penalties
Status Workflows
See the below diagrams for common status flows, with context around each update.
Standard Match
Below is the flow of the overall status of a typical Soccer game from not_started to closed.
Postponed
Below is the flow of a postponed game.
Once a new game is created in scheduled status, it follows the Standard Match flow.
Suspended
Below is the flow of a suspended match.
Once a suspended game moves back to live it follows the Standard Match flow.
Cancelled
Below is the flow of a cancelled match.
A cancelled game will remain in cancelled status. See match sr:sport_event:51567551 as an example.
Status Samples
(Coming Soon!):
- Not Started
- Live
- Ended
- Closed
General Data Workflows and Production Timelines
Here’s what you can expect for common data processes in the Soccer API:
- Schedule Releases and Tournament Creation: Fixtures are typically created within 4 hours or up to 1 month in advance, depending on priority.
- Lineups Information: Starting lineups are announced roughly 1 hour before kickoff and can change until the match begins. The latest expected availability is 15 minutes into the match.
- Player Transfers and Rosters: Transfer data is updated within 24 hours of official confirmation, based on priority.
- Translated Terms: New teams or competitions are translated within 4 weeks of creation.
- Corrections: Most corrections occur during live coverage, with post-match validation to ensure data accuracy.
- Resulting: Match results are finalized and published within 5 minutes of match completion.
Updated about 17 hours ago