How to Build a Live Race Tracker

✅ Included in All Plans

The livescores endpoint is included at no additional cost.

Plans differ only in leagues and API call limits.

Compare plans →

This guide shows you how to use the livescores endpoint to build a real-time race tracker that displays current positions, lap counts, and pit stop activity during a live session.

When to use this

Use the livescores endpoint when you want to:

• Display a live race feed with current driver positions

• Show real-time lap counts and session progress

• Track pit stops and stints as they happen during a race

How to retrieve the data

The GET All Livescores endpoint returns all currently live and near-live fixtures:

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

For a race tracker you will need position data, lap progress, and pit stop activity. Use the following includes:

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

The maximum include depth on this endpoint is 3.

Available includes for live race tracking:

Include	What it returns
state	Current fixture state (e.g. in progress, finished)
results	Current driver positions and classification
latestLaps	The most recent lap data for all drivers
latestPitstops	The most recent pit stop entries
participants	Driver and team details for the session
metadata	Session-level data: current lap count, total laps, fastest lap

To add session metadata (lap counter, race distance, fastest lap):

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

The type references for results and metadata fields are documented in:

• Results and Live Data Type Reference

• Metadata and Per-Season Data Type Reference

Working with the data

Poll the endpoint on a fixed interval to keep your UI current. A 10-15 second interval is a reasonable default - more frequent polling increases API call usage against your plan's hourly limit.

const API_TOKEN = 'your_token';

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

  // Filter to race sessions only (name === 'Race')
  const races = data.filter(fixture => fixture.name === 'Race');

  return races;
}

// Poll every 15 seconds
setInterval(fetchLiveRace, 15000);

Each fixture in the response includes the name field ("Practice 1", "Qualifying", "Race", etc.) and a length field that returns the total number of laps for race sessions.

The leg field indicates which session within a session type this is. For example, "2/3" means Practice 2 of 3. Note that leg returns "1/1" for Practice 1 when the other practice sessions are replaced by sprint sessions.

Common pitfalls

The endpoint returns all live and near-live sessions, not just races. Filter by the name field if your tracker is race-only.

latestLaps and latestPitstops return only the most recent entries, not the full race history. To retrieve full lap history for a fixture, use the GET Laps by Fixture ID endpoint after the session ends.

length means different things depending on session type. For practice and qualification sessions, length is the planned session duration in minutes. For race sessions, length is the total lap count.

Advanced usage

To show a live gap-to-leader column, extract the position value from the results include for each driver, sort by position, and calculate the time delta between position 1 and each subsequent driver. The results type reference documents the specific type_id values for position, gap, and interval data.

Common errors

Status	Likely cause
401	Missing or invalid api_token
429	Rate limit exceeded - reduce polling frequency

See also

Live endpoints

• GET All Livescores

Type references

• Results and Live Data Type Reference

• Metadata and Per-Season Data Type Reference

Related entities

• Live

• Fixture

• Lap

• Pitstop

FAQ

How often should I poll the livescores endpoint? There is no minimum interval enforced by the API, but your plan has an hourly call limit. For a typical race tracker with a handful of includes, polling every 10-15 seconds is a practical balance between freshness and call usage.

What does state_id mean in a live fixture? The state include returns the fixture's current state object. Use the GET All States endpoint (/v3/motorsport/states) to retrieve the full list of states and their IDs.

Can I retrieve live data for a specific fixture rather than all live sessions? The livescores endpoint returns all live sessions. To scope down to a single fixture, filter client-side by id after fetching, or use the GET Fixture by ID endpoint with the same includes once you know the fixture ID.