# States

> **🏎️ Motorsport API Required**
>
> All States endpoints require an active Motorsport API subscription (€79/mo, 3,000 API calls/hr).
>
> [View pricing →](https://www.sportmonks.com/formula-one-api/)

A **state** represents the current status of a motorsport fixture - for example, Not Started, Live, or Finished. Every fixture has a `state_id` field that references one of these states. Use the States endpoints to retrieve the complete list of possible states or look up a specific state by ID.

States are reference data. Fetch them once, cache them locally, and use them to decode `state_id` values across fixture, livescores, and schedule responses.

#### **Available endpoints**

* [**GET All States**](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/states/get-all-states): returns all possible fixture states in the Motorsport API.
* [**GET State by ID**](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/states/get-state-by-id): returns a specific state by its ID.

#### **Include options**

{% hint style="info" %}
No includes are available for the States endpoints. The state response is a flat reference object with no related entities to enrich.
{% endhint %}

#### **Known states**

The following states are confirmed in the Motorsport API. The complete list is returned by the GET All States endpoint - fetch it to ensure your application handles any states not listed here.

| ID   | `developer_name` | `name`      | Notes                                                     |
| ---- | ---------------- | ----------- | --------------------------------------------------------- |
| `1`  | `NS`             | Not Started | Session is scheduled but has not yet begun                |
| `5`  | `FT`             | Full Time   | Session has concluded ("Full Time" is the finished state) |
| `18` | `INTERRUPTED`    | Interrupted | Session has been suspended, e.g. red flag                 |
| `27` | `LIVE`           | Live        | Session is currently in progress                          |

{% hint style="info" %}
The "finished" state is **Full Time** (`FT`, ID: `5`), not `"Finished"`. This terminology is inherited from football. Filter for `state_id: 5` or `developer_name: "FT"` when querying for completed sessions.
{% endhint %}

#### **Working with state fields**

Each state object has four string fields that can appear similar:

* **`developer_name`** - the value recommended for use in your application code. Use this for all programmatic state checks - it is the most stable identifier.
* **`name`** - the human-readable label. Use this for UI display (e.g. a status badge).
* **`short_name`** - an abbreviated label for compact displays.
* **`state`** - the legacy abbreviation field. For most states this is identical to `developer_name`. Prefer `developer_name` in new integrations.

For the four known states, all four fields carry the same or very similar values. The distinction matters more in other Sportmonks v3 APIs where these fields diverge.

#### **Using states in your application**

The recommended pattern is to fetch all states once at startup and build a local lookup map keyed by `id`:

{% tabs %}
{% tab title="Javascript" %}

```
// Fetch once and cache
async function loadStates(token) {
  const res = await fetch(
    `https://api.sportmonks.com/v3/motorsport/states?api_token=${token}`
  );
  const { data } = await res.json();

  // Build lookup by ID
  return Object.fromEntries(data.map(s => [s.id, s]));
}

// Use throughout your app
const states = await loadStates(YOUR_TOKEN);

// Decode a fixture's state_id
const fixture = { state_id: 27, name: 'Race' };
const stateLabel = states[fixture.state_id]?.name ?? 'Unknown';
console.log(`${fixture.name}: ${stateLabel}`); // "Race: Live"
```

{% endtab %}

{% tab title="Python" %}

```
import requests

def load_states(token):
    res = requests.get(
        f'https://api.sportmonks.com/v3/motorsport/states',
        params={'api_token': token}
    )
    data = res.json()['data']
    return {s['id']: s for s in data}

# Use throughout your app
states = load_states(YOUR_TOKEN)

fixture = {'state_id': 5, 'name': 'Race'}
state_label = states.get(fixture['state_id'], {}).get('name', 'Unknown')
print(f"{fixture['name']}: {state_label}")  # "Race: Full Time"
```

{% endtab %}
{% endtabs %}

States are stable reference data - they rarely if ever change. Cache them with a long TTL (24 hours or more) and refresh only on application restart or cache miss.

#### **Checking for live sessions**

To check whether a fixture is currently active, compare `state_id` against the LIVE state (`id: 27`):

```javascript
const isLive = fixture.state_id === 27;

// Or use developer_name if you have the state object
const isLive = state.developer_name === 'LIVE';
```

For a full list of currently live fixtures, use the [Live endpoint](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/live) directly - it is more efficient than fetching all fixtures and filtering by state.

#### **Related entities**

Get an overview and explanation of all the fields returned in the API response:

* [State](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/state)

#### **Related pages**

* [Fixtures](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/fixtures) - The `state_id` field on fixtures resolves to a state
* [Live](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/live) - Active fixtures filtered by live state
* [Schedules](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/schedules) - Schedule responses include `state_id` on each fixture


---

# 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/motorsport-api/endpoints-and-entities/endpoints/states.md?ask=<question>
```

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.