Status codes
The status_code field is a small integer that tells you exactly which phase
of the match lifecycle you're looking at.
| Code | Name | Description |
|---|---|---|
| 1 | Scheduled | Match exists but has not kicked off yet. minute and period are null. |
| 2 | Live | Currently in play. period, minute and (for basketball) game_clock_secs are populated. |
| 3 | Finished | Final whistle. home_score / away_score are settled. finished_at is set. |
| 4 | Postponed | Rescheduled to a later date. kickoff_ts may have been updated. |
| 5 | Cancelled | Will not take place. |
| 6 | Walkover | One team did not appear; the other is awarded the win. |
| 7 | Interrupted | Temporarily halted (weather, injury). May return to 2 (Live). |
| 8 | Abandoned | Stopped without resumption. Score at the time of abandonment is preserved. |
| 9 | After Penalties | Decided by a penalty shoot-out. The score reflects the result before penalties; events / stats include the shoot-out detail. |
| 10 | After Extra Time | Decided in extra time without going to penalties. |
Filtering by status
The list endpoint accepts a friendly enum:
?status= | Includes codes |
|---|---|
live | 2 |
scheduled | 1 |
finished | 3, 9, 10 |
Other states (4 postponed, 5 cancelled, 6 walkover, 7 interrupted,
8 abandoned) are visible in the unfiltered response.
Suggested UI mapping
| Code | Suggested UI string |
|---|---|
| 1 | "Today, 19:30" (kickoff) |
| 2 | "63'" (football) or "Q3 7:42" (basketball) |
| 3 | "FT 2-1" |
| 4 | "Postponed" |
| 5 | "Cancelled" |
| 6 | "Walkover" |
| 7 | "Interrupted" |
| 8 | "Abandoned" |
| 9 | "AET (Pens)" |
| 10 | "AET" |
Transitions to watch
When listening over WebSocket, you'll receive a
status_change event every time status_code changes. The most common
transitions in practice are:
1 → 2— kickoff.2 → 3— full time.2 → 7 → 2— interruption then resumption.2 → 9/2 → 10— extra time / penalties.
Build your UI to react to each transition individually so a delayed event doesn't desync the display.