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 machineMatch status state machine

Match status state machine

Not started

Matches always start with the Not Started status. In this state:

  • status is not_started
  • scheduled_at is the official 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 prior to 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

🚧

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 twiceMatch rescheduled twice

Match rescheduled twice

Running

Matches status is updated to Running as soon as the match starts. In this state:

  • status is running
  • 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 is finished
  • end_at is set to the match finish time
  • winner_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 is canceled
  • forfeit is false
  • begin_at is null
  • end_at is null

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 is canceled
  • forfeit is true
  • begin_at is null
  • end_at is null
  • 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 rescheduledPostponed match rescheduled

Postponed match rescheduled


Did this page help you?