Session states
This guide covers how session states work in the Motorsport API, what fields the State entity contains, and how to use states reliably in your application without hardcoding IDs.
When to use this
Use session states when you want to:
Detect whether a session is scheduled, live, or finished
Show a status badge on a fixture card
Gate logic in your application (e.g. only start polling live data when a session is active)
Filter fixtures by state
What a state is
Every fixture has a state_id field. This is a foreign key that refers to a State entity. The State entity describes the current lifecycle status of the session.
The State entity has the following fields:
id
integer
The unique ID of the state
state
string
The abbreviation of the state
name
string
The full human-readable name of the state
short_name
string
A short version of the name
developer_name
string
The recommended stable identifier for use in code
developer_name is the field to use in your application logic. It is the stable, consistent identifier that does not change between API versions. Avoid hardcoding id values in conditional logic.
Fetching all states
Fetch the full list of states once at startup and cache them locally:
States are reference data that rarely change. Fetching them once and storing them in memory or a local cache saves API calls and means you can resolve any state_id instantly without an extra include on every fixture request.
Including state on a fixture or livescore
To get the state object alongside a fixture in the same request:
Response (partial):
Working with the data
Build a local state lookup
Fetch states once and build a lookup map so you never need to include state on every fixture request:
Gate live polling on session state
Use developer_name rather than state_id in conditional logic so your code is readable and resilient to any future state ID changes:
Display a human-readable status badge
Common pitfalls
Hardcoding state IDs. State IDs are internal integers that are consistent but not guaranteed to be meaningful across contexts. Use developer_name in your conditional logic ("INPLAY", "FT", "NS") so the intent is readable and the code is not brittle to any future numbering changes.
Including state on every live poll. States are reference data that do not change during a session. Fetch them once at startup, build a local lookup, and resolve state_id locally. This removes one include from every polling request, reducing payload size and query complexity.
Assuming state_id is set immediately. Newly created fixtures may have a null state_id before they are assigned a state. Always check for null before looking up state data.
Common errors
401
Missing or invalid api_token
404
The state ID does not exist in the States endpoint
See also
Related tutorials
Reference
FAQ
Where do I find the full list of state values? Call GET https://api.sportmonks.com/v3/motorsport/states?api_token={your_token} to retrieve every state with its id, name, short_name, and developer_name.
Does a session go from scheduled directly to live? State transitions depend on the session lifecycle managed on Sportmonks' side. Fetch states periodically and use developer_name to respond to transitions rather than polling for a specific ID.
Is there a state for sessions that have been postponed or cancelled? The States endpoint returns the full list of possible states. Fetch it to see all values, including any for postponed or cancelled sessions.
Why does state have no include options? The State entity has no nested includes. All the data you need is on the state object itself.
Last updated
Was this helpful?