🟢States

🏎️ Motorsport API Required

All States endpoints require an active Motorsport API subscription (€79/mo, 3,000 API calls/hr).

View pricing →

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: returns all possible fixture states in the Motorsport API.

• GET State by ID: returns a specific state by its ID.

Include options

No includes are available for the States endpoints. The state response is a flat reference object with no related entities to enrich.

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

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.

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:

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"

Python

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):

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 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

Related pages

• Fixtures - The state_id field on fixtures resolves to a state

• Live - Active fixtures filtered by live state

• Schedules - Schedule responses include state_id on each fixture