States

The state include adds the current match status to a fixture. Use state_id for logic and filtering, and the returned names for display.

Request state information

GET https://api.sportmonks.com/v3/football/fixtures/{{fixtureId}}?api_token={{apiToken}}&include=state

The fixture’s state_id matches state.id. For example, a second-half extra-time state is:

{
  "id": 23,
  "state": "INPLAY_ET_2ND_HALF",
  "name": "ET - 2nd Half",
  "short_name": "2et",
  "developer_name": "INPLAY_ET_SECOND_HALF"
}

Complete state reference

The API response checked on 15 October 2026 returned these 25 states with no further pages. Values below are copied exactly, including case. The States definitions reference is the canonical lookup.

id	state	name	short_name	developer_name
1	NS	Not Started	NS	NS
2	INPLAY_1ST_HALF	1st Half	1st	INPLAY_1ST_HALF
3	HT	Half Time	HT	HT
4	BREAK	Break	BRK	BREAK
5	FT	Full Time	FT	FT
6	INPLAY_ET	Extra Time	et	INPLAY_ET
7	AET	After Extra Time	AET	AET
8	FT_PEN	After Penalties	FTP	FT_PEN
9	INPLAY_PENALTIES	Penalties	PEN	INPLAY_PENALTIES
10	POSTPONED	Postponed	POST	POSTPONED
11	SUSPENDED	Suspended	SUSP	SUSPENDED
12	CANCELLED	Cancelled	CANC	CANCELLED
13	TBA	To Be Announced	TBA	TBA
14	WO	Walk Over	WO	WO
15	ABANDONED	Abandoned	ABAN	ABANDONED
16	DELAYED	Delayed	DELA	DELAYED
17	AWARDED	Awarded	AWAR	AWARDED
18	INTERRUPTED	Interrupted	INT	INTERRUPTED
19	AWAITING_UPDATES	Awaiting Updates	AU	AWAITING_UPDATES
20	DELETED	Deleted	DEL	DELETED
21	EXTRA_TIME_BREAK	Extra Time - Break	ETB	EXTRA_TIME_BREAK
22	INPLAY_2ND_HALF	2nd Half	2nd	INPLAY_2ND_HALF
23	INPLAY_ET_2ND_HALF	ET - 2nd Half	2et	INPLAY_ET_SECOND_HALF
25	PEN_BREAK	Penalties - Break	PENB	PEN_BREAK
26	PENDING	Pending	PEN	PENDING

Use identifiers, not display labels, for logic. The short_name PEN belongs to both Penalties (9) and Pending (26). Also, state and developer_name differ for state 23. Do not derive one field from another or match on a shortened label.

Match phases

Typical regulation phases are NS (1), INPLAY_1ST_HALF (2), HT (3), INPLAY_2ND_HALF (22) and FT (5). If extra time is played, the relevant phases include BREAK (4), INPLAY_ET (6), EXTRA_TIME_BREAK (21), INPLAY_ET_2ND_HALF (23) and AET (7). Penalties use PEN_BREAK (25), INPLAY_PENALTIES (9) and FT_PEN (8).

These are phase guides, not a guarantee that every match visits every state or that polling observes every intermediate change. Re-read the current fixture state, handle interruptions and schedule changes, and allow for later data corrections. A Full Time label does not by itself guarantee that no further competition phase or update will follow.

Filter fixtures by state

For actively playing phases, include both regulation halves, both extra-time halves and penalties:

GET https://api.sportmonks.com/v3/football/fixtures?api_token={{apiToken}}&include=state;participants&filters=fixtureStates:2,22,6,23,9

State 7 is After Extra Time and state 10 is Postponed; neither belongs in the active-play filter. Breaks (3, 4, 21, 25) and interruptions (11, 18) are separate states. Include those separately if your match-centre view needs them.

For fixtures with completion labels:

GET https://api.sportmonks.com/v3/football/fixtures?api_token={{apiToken}}&include=state&filters=fixtureStates:5,7,8

For postponed, suspended, cancelled, abandoned, delayed or interrupted fixtures:

GET https://api.sportmonks.com/v3/football/fixtures?api_token={{apiToken}}&include=state&filters=fixtureStates:10,11,12,15,16,18

Use commas between IDs within a fixtureStates filter, and semicolons between separate includes or separate filters. Check pagination before treating a fixtures response as complete.

Classify phases in JavaScript

const ACTIVE_PLAY_IDS = new Set([2, 22, 6, 23, 9]);
const BREAK_IDS = new Set([3, 4, 21, 25]);
const COMPLETION_IDS = new Set([5, 7, 8]);

function fixturePhase(fixture) {
  const id = fixture.state_id ?? fixture.state?.id;
  if (ACTIVE_PLAY_IDS.has(id)) return "active";
  if (BREAK_IDS.has(id)) return "break";
  if (COMPLETION_IDS.has(id)) return "completion";
  return "other";
}

function stateLabel(fixture) {
  return fixture.state?.short_name ?? fixture.state?.name ?? "Unknown";
}

Classify phases in Python

ACTIVE_PLAY_IDS = {2, 22, 6, 23, 9}
BREAK_IDS = {3, 4, 21, 25}
COMPLETION_IDS = {5, 7, 8}

def fixture_phase(fixture):
    state = fixture.get("state") or {}
    state_id = fixture.get("state_id")
    if state_id is None:
        state_id = state.get("id")
    if state_id in ACTIVE_PLAY_IDS:
        return "active"
    if state_id in BREAK_IDS:
        return "break"
    if state_id in COMPLETION_IDS:
        return "completion"
    return "other"

Notifications and refreshing

Compare a fixture’s current state ID with the previously stored ID. Keep that previous-state map between polling requests; recreating it inside each request cannot detect changes. Useful notification mappings include 22 for the second half, 6 for extra time, 23 for extra-time second half, 9 for penalties, 10 for postponed and 12 for cancelled.

Choose refresh intervals for your application and request allowance. Do not permanently stop synchronising solely because a fixture once returned FT, AET or FT_PEN: later corrections or state changes may matter to your product. Treat an absent state object as unavailable data and handle it explicitly.

Related documentation

States definitions · GET All States · Events include · Periods include