🛰️States

Fixture status definitions

A fixture moves through several possible statuses during its lifecycle, from scheduled to finished (or cancelled). You can use these states to determine match progress in real time or filter data using the states endpoint.

🧭 Overview

Each fixture starts with an initial state and transitions through several phases depending on the match’s progress, delays, or interruptions. States are identified by both a numeric ID and a state code (used in the API).

Use:

GET /v3/football/states?api_token=YOUR_TOKEN

to retrieve the full list programmatically.

⚽ State reference table

ID	Name	State	Description
1	Not Started	NS	The initial status of a fixture.
2	1st Half	INPLAY_1ST_HALF	The game is in play (first half).
3	Half-Time	HT	The match is currently in half-time.
4	Regular Time Finished	BREAK	Waiting for extra time to start.
5	Full-Time	FT	The game ended after 90 minutes. When going to extra time, this appears briefly before BREAK.
6	Extra Time	INPLAY_ET	Extra time (first half) is in progress.
7	Finished After Extra Time	AET	The match has ended after 120 minutes.
8	Full-Time After Penalties	FT_PEN	The match finished following a penalty shootout.
9	Penalty Shootout	INPLAY_PENALTIES	Penalties are being taken to decide the winner.
10	Postponed	POSTPONED	The match has been postponed to another date.
11	Suspended	SUSPENDED	The match is suspended and will continue later.
12	Cancelled	CANCELLED	The match has been permanently cancelled.
13	To Be Announced	TBA	Fixture has no confirmed date/time yet.
14	Walk Over	WO	A victory was awarded because no opponent was available.
15	Abandoned	ABANDONED	The match was abandoned and will resume later.
16	Delayed	DELAYED	Kick-off has been delayed.
17	Awarded	AWARDED	Winner decided externally (administrative decision).
18	Interrupted	INTERRUPTED	Temporarily stopped (e.g., bad weather).
19	Awaiting Updates	AWAITING_UPDATES	Temporary state due to data or connectivity delay.
20	Deleted	DELETED	The fixture is no longer active in standard calls but can still be fetched with deleted=1.
21	Extra Time Break	EXTRA_TIME_BREAK	Short break between extra time halves.
22	2nd Half	INPLAY_2ND_HALF	The game is in play (second half).
25	Penalties Break	PEN_BREAK	Waiting for penalties to start.
26	Pending	PENDING	The fixture awaits new data or verification.

🧩 Developer usage examples

Example 1: Filtering fixtures by state Fetch all in-play matches:

https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN

Example 2: Display match progress dynamically When state_id changes from 2 → 3 → 22 → 5, you can update a live UI to show:

"1st Half" → "Half-Time" → "2nd Half" → "Full-Time"

Example 3: Detect postponed or cancelled games

GET /v3/football/fixtures?api_token=YOUR_TOKEN&filters=state_id:10,12

Returns all fixtures with a Postponed or Cancelled status.

🧠 Best practices

• Always use state_id or state.name to track match progression.

• Combine state data with starting_at timestamps for precise scheduling.

• Expect temporary states like AWAITING_UPDATES or INTERRUPTED in live games.

• Use DELETED states to sync fixtures that have been replaced.