Fixtures

This guide covers how to retrieve fixtures, understand the different session types within a race weekend, and enrich fixture responses with results, lineups, and session metadata.

When to use this

Use the Fixtures endpoints when you want to:

• Retrieve a specific session by its ID

• Get all sessions across a season or date range

• Enrich a session with its results, lineup, lap data, or track metadata

• Check the current state of a session or how many laps have been completed

• Detect recently updated fixtures for syncing a local database

What a fixture is

A fixture is a single session within a race weekend: a practice session, qualifying session, sprint qualifying, sprint race, or the main race. Multiple fixtures belong to a stage (race weekend), which belongs to a season, which belongs to a league.

The Fixture entity fields

Field	Description	Type
id	Unique ID of the fixture	integer
sport_id	Sport ID (2 for Motorsport)	integer
league_id	The championship this session belongs to	integer
season_id	The season this session belongs to	integer
stage_id	The race weekend this session belongs to	integer
state_id	The current state of the session	integer
venue_id	The circuit where this session is held	integer
name	The session name (e.g. "Practice 1", "Race")	string
starting_at	Start date and time in UTC	date
starting_at_timestamp	Start time as a Unix timestamp	integer
result_info	Final result summary (populated after session ends)	string
leg	Session position within its type (e.g. "2/3" for Practice 2 of 3)	string
details	Additional details about the session	string
placeholder	Whether this is a placeholder fixture	boolean

group_id, aggregate_id, round_id, has_odds, has_premium_odds, and length are not used in the Motorsport API.

The Fixtures endpoints

The Fixtures section has six endpoints:

Endpoint	Description
GET /motorsport/fixtures	All fixtures in your subscription
GET /motorsport/fixtures/{id}	A single fixture by ID
GET /motorsport/fixtures/multi/{ids}	Multiple fixtures by comma-separated IDs
GET /motorsport/fixtures/latest	All fixtures updated in the past 10 seconds
GET /motorsport/fixtures/date/{date}	All fixtures on a specific date (YYYY-MM-DD)
GET /motorsport/fixtures/between/{start}/{end}	All fixtures between two dates

Available includes

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

Retrieving fixtures

Get a single fixture by ID:

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

Get all fixtures for a season:

GET https://api.sportmonks.com/v3/motorsport/fixtures
?api_token={your_token}&filters=fixtureSeasons:25273

Get all fixtures on a specific date:

GET https://api.sportmonks.com/v3/motorsport/fixtures/date/2025-03-16
?api_token={your_token}

Get all fixtures between two dates:

GET https://api.sportmonks.com/v3/motorsport/fixtures/between/2025-03-14/2025-03-16
?api_token={your_token}

Get fixtures recently updated (for sync workflows):

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

Enriching fixtures

With state and venue:

GET https://api.sportmonks.com/v3/motorsport/fixtures/19408487
?api_token={your_token}&include=state;venue

With results and lineups:

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

With session metadata (lap count, fastest lap, race distance):

GET https://api.sportmonks.com/v3/motorsport/fixtures/19408487
?api_token={your_token}&include=metadata

The metadata include returns session-level data typed by ID. The confirmed fixture metadata types are:

ID	Developer Name	Description
9737	IS_QUALIFICATION	Whether the session is part of a qualifying segment
9734	SPRINT_RACE	Whether the session is a sprint race with sprint points
164	HAS_STANDING	Whether the session contributes to championship standings
172	SPLIT_POINTS_RULE	Whether the half points rule applies
9736	CURRENT_LAP	Current lap number (live sessions)
105427	TOTAL_LAPS	Total lap count for the session
9716	FASTEST_LAP	Fastest lap time and lap number
114509	RACE_DISTANCE	Race distance in kilometres
110619	LEGACY_ID	The v1 stage ID for migration purposes

Match metadata entries by their type_id to identify which value you are reading.

Working with the data

Get a fixture with full session context

JavaScript

const API_TOKEN = 'your_token';

async function getFixture(fixtureId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/fixtures/${fixtureId}
     ?api_token=${API_TOKEN}&include=state;venue;metadata`
  );
  const { data } = await response.json();
  return data;
}

Python

PHP

Read a metadata value by developer name

METADATA_DEVELOPER_NAMES = {
    9736: "CURRENT_LAP",
    105427: "TOTAL_LAPS",
    9716: "FASTEST_LAP",
    114509: "RACE_DISTANCE",
    164: "HAS_STANDING",
    9734: "SPRINT_RACE",
}

def get_metadata_value(fixture, developer_name):
    for entry in fixture.get("metadata", []):
        if METADATA_DEVELOPER_NAMES.get(entry["type_id"]) == developer_name:
            return entry.get("value")
    return None

total_laps = get_metadata_value(fixture, "TOTAL_LAPS")
fastest_lap = get_metadata_value(fixture, "FASTEST_LAP")

const METADATA_TYPE_IDS = {
  CURRENT_LAP: 9736,
  TOTAL_LAPS: 105427,
  FASTEST_LAP: 9716,
  RACE_DISTANCE: 114509,
  HAS_STANDING: 164,
  SPRINT_RACE: 9734,
};

function getMetadataValue(fixture, developerName) {
  const typeId = METADATA_TYPE_IDS[developerName];
  const entry = fixture.metadata?.find(m => m.type_id === typeId);
  return entry?.value ?? null;
}

const totalLaps = getMetadataValue(fixture, 'TOTAL_LAPS');
const fastestLap = getMetadataValue(fixture, 'FASTEST_LAP');

Get all fixtures for a race weekend

JavaScript

async function getWeekendSessions(stageId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/fixtures
     ?api_token=${API_TOKEN}&filters=fixtureStages:${stageId}&include=state`
  );
  const { data } = await response.json();
  return data.sort((a, b) => new Date(a.starting_at) - new Date(b.starting_at));
}

Python

PHP

Detect a sprint weekend

def is_sprint_weekend(stage_id):
    sessions = get_weekend_sessions(stage_id)
    session_names = [s["name"] for s in sessions]
    return "Sprint" in session_names

async function isSprintWeekend(stageId) {
  const sessions = await getWeekendSessions(stageId);
  return sessions.some(s => s.name === 'Sprint');
}

Understanding the leg field

The leg field encodes a session's position within its session type:

leg value	Meaning
"1/3"	Practice 1 of 3
"2/3"	Practice 2 of 3
"3/3"	Practice 3 of 3 (or Qualifying 3 of 3)
"1/1"	A single session of its type (Race, or Practice 1 when sprint weekend replaces other practice sessions)

On a standard weekend, Practice 1 returns "1/3". On a sprint weekend where practice sessions are reduced, Practice 1 returns "1/1" since there are no further practice sessions of that type.

Common pitfalls

Using GET All Fixtures without a filter. This returns your entire subscription, which can be thousands of records across all seasons. Always scope your request with fixtureSeasons, fixtureStages, or a date-based endpoint.

Reading length for lap count. The length field is listed as currently unused in the Motorsport API. Use the TOTAL_LAPS metadata type (ID 105427) via &include=metadata for the lap count instead.

Assuming result_info is populated. result_info is only filled after a session has finished. For live race position data, use &include=results or &include=lineups.details.

Treating leg as a round number. leg is the session's position within its own session type, not the round number within the season. Use stage.sort_order for the round number.

group_id, aggregate_id, and round_id are not used. These fields exist for cross-sport compatibility but will always be null in motorsport responses.

Common errors

Status	Likely cause
401	Missing or invalid api_token
404	The fixture_id does not exist or is not in your subscription
422	Query complexity exceeded - reduce nested includes

See also

Related tutorials

• Session states

• Retrieving results

• Lineups

• Stages

• Live sessions

Reference

• Fixture entity

• Metadata and Per-Season Data Type Reference

• Results and Live Data Type Reference

FAQ

What is the difference between a fixture and a livescore? A fixture is a session at any point in time: past, present, or future. A livescore is the same data filtered to a 15-minute active window around a session. Use livescores for real-time polling and fixtures for everything else.

How do I find a fixture ID if I only know the race date? Use GET /motorsport/fixtures/date/{YYYY-MM-DD} or GET /motorsport/fixtures/between/{start}/{end} with a date range covering the race weekend, then filter by name for the specific session type.

How do I know if a fixture has been updated recently? Use GET /motorsport/fixtures/latest which returns all fixtures updated in the past 10 seconds. This is the recommended approach for keeping a local database in sync without re-fetching the full dataset.

Can I retrieve multiple specific fixtures in one call? Yes. Use GET /motorsport/fixtures/multi/{ids} with a comma-separated list of fixture IDs.

How do I tell if a session counts towards the championship standings? Include metadata and check the HAS_STANDING type (ID 164). A value of true means the session results contribute to the driver and constructor championships.