Matches lifecycle

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).

Not started

Matches always start with the not_started status. In this state:

status is not_started
scheduled_at is the official match playing time — as announced by the organizer
begin_at has the same value as scheduled_at (to support some legacy integrations)
end_at is null

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 is true
scheduled_at is the new official playing time — as announced by the organizer
original_scheduled_at is the initial official playing time

An example of a match which is rescheduled from date_1 to date_2

🚧
Warning
Matches will only be marked as rescheduled when the organizer officially announces a new date. Matches that are delayed (e.g. because the previous match is not finished) will not be marked as rescheduled.

Running

Match status is updated to running as soon as the match begins. In this state:

status is running
begin_at is set to the actual beginning time of the match

An example of a match which begins at date_2, transitioning to the running status

Finished

Match status is updated to finished as soon as the match ends. In this state:

status is finished
end_at is set to the match finish time
winner_id is updated to the winning team/player id

Complete games

For matches that support historical data (i.e. detailed_stats is true) the 'complete' field indicates whether post-game statistics are whole and available for user consumption. Once a match is complete, the data should not change. In this state:

status is finished
complete is true

An example of a match which is complete, meaning all statistics are 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 is canceled
forfeit is false
begin_at is null
end_at is null

A match enters the 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 is canceled
forfeit is true
begin_at is null
end_at is null
winner_id is updated to the winning team/player id

An example of a match which has been forfeited by team_2

Postponed

Match status is updated to postponed when the match is rescheduled to an unknown date. In this state:

status is postponed
scheduled_at is not updated

When a new playing date is known, postponed matches go through the same procedure as rescheduled matches.

Example