Matches lifecycle
Learn how PandaScore REST API handles matches life cycle, from start to finish.
PandaScore implements match statuses as a finite state machine. The diagram below is a recap of all existing match statuses (the states) and the events that can affect them (the transitions).

Match status state machine
Not started
Matches always start with the Not Started status. In this state:
status
isnot_started
scheduled_at
is the official playing time — as announced by the organizerbegin_at
has the same value asscheduled_at
(to support some legacy integrations)end_at
isnull
For matches that support real-time in-game data, the WebSocket opens 15 minutes before the scheduled time.
Retrieve the list of open WebSockets with the All video games > List live matches endpoint.
Rescheduled matches
When an organizer decides to reschedule match, the rescheduled
field will be set to true
. In this state:
rescheduled
istrue
scheduled_at
is the new official playing time — as announced by the organizeroriginal_scheduled_at
is the initial official playing time
Warning
Matches will only be marked as rescheduled when the organizer officially announces a new date. Matches that are delayed (eg. because the previous match is not finished) will not be marked as rescheduled.
Example
Match rescheduled twice
Running
Matches status is updated to Running as soon as the match starts. In this state:
status
isrunning
begin_at
is set to the actual begin time of the match
Finished
Matches status is updated to Finished as soon as the match ends. In this state:
status
isfinished
end_at
is set to the match finish timewinner_id
is set
For matches that support historical data (ie. detailed_stats
is true
), the post-game statistics will be available.
Canceled
Sometimes, matches can be canceled. Reasons may vary and different scenarios exist: cancellation by the organizer or one participant forfeiting.
Without winner
In this scenario, the match status is updated to Canceled
. In this state:
status
iscanceled
forfeit
isfalse
begin_at
isnull
end_at
isnull
A match goes in Canceled
status when, for various potential reasons, it won't be played.
Forfeit
In this scenario too, the match status is updated to Canceled
. However, in this state:
status
iscanceled
forfeit
istrue
begin_at
isnull
end_at
isnull
winner_id
is set
Postponed
Matches status is updated to Postponed when the match is postponed to an unknown date. In this state, the match status
is postponed
but the scheduled_at
is not updated.
As a new playing date is known, postponed matches go through the same procedure as rescheduled matches.
Example
Postponed match rescheduled
Updated 3 months ago