# 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](https://app.gitbook.com/u/IUBUJiafDZcMtsn0kjaw4GNJJwA2).

#### 🧭 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.