Live sessions

This guide covers how to retrieve currently active sessions using the Live endpoints, what data is available during a live session, and how to structure your polling strategy.

When to use this

Use the Live endpoints when you want to:

Display sessions that are currently in progress or starting within the next 15 minutes
Build a live race tracker that updates as the session unfolds
Receive the most recent lap, pitstop, and result data without querying fixtures directly
Detect when a session has recently finished (within the past 15 minutes)

For sessions outside this window (past results, upcoming fixtures), use the Fixtures endpoints instead.

The Live endpoints

The Live entity has two endpoints:

GET All Livescores - returns all sessions that are live, starting within 15 minutes, or finished within the past 15 minutes:

GET https://api.sportmonks.com/v3/motorsport/livescores
?api_token={your_token}

GET Latest Updated Livescores - returns all livescores that have received an update within the past 10 seconds:

GET https://api.sportmonks.com/v3/motorsport/livescores/latest
?api_token={your_token}

Use GET Latest Updated Livescores for your main polling loop. It returns only sessions with recent changes, which means smaller payloads and faster responses compared to fetching all active sessions on every poll.

The response structure

The Live entity returns the same fields as the Fixture entity, since a livescore is a fixture filtered by its active time window:

{
  "data": [
    {
      "id": 19408487,
      "sport_id": 2,
      "league_id": 3468,
      "season_id": 25273,
      "stage_id": 77475992,
      "state_id": 3,
      "venue_id": 343575,
      "name": "Race",
      "starting_at": "2025-03-16 15:00:00",
      "leg": "1/1",
      "placeholder": false,
      "starting_at_timestamp": 1742137200
    }
  ]
}

state_id tells you the current session state. Include state to get the human-readable label alongside it. See Session states for the full state reference.

Available includes

The Live endpoint supports the following includes:

sport stage league season venue state lineups participants metadata results latestLaps pitstops latestPitstops stints latestStints

Note latestLaps, latestPitstops, and latestStints. These return only the most recent entry per driver, rather than the full session history. Use them during active polling to keep payloads small. Use laps, pitstops, and stints (via the Fixtures endpoint) when you need the complete session dataset after a race is finished.

Enriching the live response

A minimal live request with state and current positions:

GET https://api.sportmonks.com/v3/motorsport/livescores/latest
?api_token={your_token}&include=state;results

With driver names attached:

GET https://api.sportmonks.com/v3/motorsport/livescores/latest
?api_token={your_token}&include=state;lineups.driver;results

With the latest lap per driver:

GET https://api.sportmonks.com/v3/motorsport/livescores/latest
?api_token={your_token}&include=state;results;latestLaps

Working with the data

Poll for live session updates

const API_TOKEN = 'your_token';

async function pollLiveSessions() {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/livescores/latest?api_token=${API_TOKEN}&include=state;results;latestLaps`
  );
  const { data } = await response.json();
  return data ?? [];
}

setInterval(async () => {
  const sessions = await pollLiveSessions();
  sessions.forEach(session => {
    console.log(`${session.name} - state_id: ${session.state_id}`);
  });
}, 10000);

import requests
import time

API_TOKEN = "your_token"

def poll_live_sessions():
    url = "https://api.sportmonks.com/v3/motorsport/livescores/latest"
    params = {
        "api_token": API_TOKEN,
        "include": "state;results;latestLaps"
    }
    response = requests.get(url, params=params)
    return response.json().get("data", [])

while True:
    sessions = poll_live_sessions()
    for session in sessions:
        print(f"{session['name']} - state_id: {session['state_id']}")
    time.sleep(10)

<?php
function pollLiveSessions(string $apiToken): array {
    $url = "https://api.sportmonks.com/v3/motorsport/livescores/latest?api_token={$apiToken}&include=state;results;latestLaps";
    $response = json_decode(file_get_contents($url), true);
    return $response['data'] ?? [];
}

while (true) {
    $sessions = pollLiveSessions('your_token');
    foreach ($sessions as $session) {
        echo "{$session['name']} - state_id: {$session['state_id']}\n";
    }
    sleep(10);
}

Detect when a session goes live

Rather than inspect state_id directly against a magic number, include state and check the developer_name field, which is the stable string identifier for each state:

def is_live(session):
    state = session.get("state")
    if not state:
        return False
    return state.get("developer_name") == "INPLAY"

function isLive(session) {
  return session.state?.developer_name === 'INPLAY';
}

See Session states for all developer_name values.

Polling strategy

Keep your polling requests lean. Each include adds to payload size and query complexity.

Recommended split:

Every 10 seconds: livescores/latest with state;results for position and gap data.
Every 30-60 seconds: livescores/latest with latestLaps for lap timing.
Once per session: Fetch lineups.driver from the Fixtures endpoint at session start and cache driver names locally. Do not include this on every live poll.

Caching reference data (driver names, team names, state labels) locally reduces both payload size and query complexity on every poll.

See Query complexity for how each include affects your complexity score.

Common pitfalls

Querying GET All Livescores instead of GET Latest Updated Livescores for polling. GET All Livescores returns everything in the 15-minute window, including sessions with no recent changes. For a polling loop, latest is almost always the right choice.

Including laps instead of latestLaps during a live session. laps returns the complete lap history for the session, which grows with every lap completed. Use latestLaps during live polling and switch to laps via the Fixtures endpoint when you want the full dataset post-race.

Expecting live data outside the 15-minute window. The livescores endpoints do not return historical or future sessions. If a race finished more than 15 minutes ago, query the Fixtures endpoint by ID instead.

Not handling an empty data array. Between sessions there may be no active livescores. Always check that data is non-empty before trying to read session fields.

Common errors

Status

Likely cause

401

Missing or invalid api_token

429

Rate limit exceeded - reduce polling frequency or split includes across separate requests

422

Query complexity exceeded - remove includes until the request succeeds

FAQ

What is the difference between GET All Livescores and GET Latest Updated Livescores? GET All Livescores returns everything in the 15-minute active window regardless of when it last changed. GET Latest Updated Livescores returns only sessions updated in the past 10 seconds. Use the latter for polling.

What happens if no sessions are live? Both endpoints return a 200 response with an empty data array. This is expected behaviour between sessions.

Can I filter live sessions by league? The Live endpoints share the same filter architecture as Fixtures. Check the Live endpoint's own Dynamic Filters tab for confirmed filter support.

Does the live endpoint count against the Fixture entity rate limit? Yes. The Live endpoints use the same underlying Fixture entity, so calls against /livescores count toward the same hourly rate limit bucket as calls against /fixtures.

Last updated 11 days ago

Was this helpful?