# 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sportmonks.com/v3/definitions/states.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.