> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/states.md). # 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](https://docs.sportmonks.com/v3/definitions/states) 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](https://docs.sportmonks.com/v3/definitions/states) · [GET All States](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/states/get-all-states) · [Events include](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/events) · [Periods include](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/periods) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/states.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.