Stages

This guide covers how stages work in the Motorsport API, how to retrieve them, and how to use them to access the sessions within a race weekend.

When to use this

Use the Stages endpoints when you want to:

Retrieve a specific race weekend by its ID
List all race weekends in a season with their dates and status
Get all sessions (fixtures) for a specific race weekend
Check whether a race weekend is finished or currently active

What a stage is

A stage represents a race weekend. It groups all the individual sessions at a single circuit: practice sessions, qualifying, the sprint race (if applicable), and the main race. Each session within the weekend is a Fixture.

Stage (race weekend: "Bahrain Grand Prix 2025")
  └── Fixtures
        ├── Practice 1
        ├── Practice 2
        ├── Practice 3
        ├── Qualifying
        └── Race

The Stage entity fields

Field

Description

id

Unique ID of the stage

sport_id

Sport ID (2 for Motorsport)

league_id

The championship this weekend belongs to

season_id

The season this weekend belongs to

type_id

The stage type (e.g. race weekend, test session)

name

The name of the race weekend (e.g. "Bahrain Grand Prix 2025")

sort_order

The round number within the season

finished

Whether the weekend is complete

is_current

Whether this is the current active race weekend

starting_at

Start date of the weekend

ending_at

End date of the weekend

games_in_current_week and tie_breaker_rule_id are not used in the Motorsport API.

Retrieving stages

Get all stages for a season:

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

Get a specific stage by ID:

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

Get all sessions within a stage:

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

Get stages with their type resolved:

GET https://api.sportmonks.com/v3/motorsport/stages/{stage_id}
?api_token={your_token}&include=type

Available includes

sport league season type fixtures

Working with the data

List all race weekends in a season

const API_TOKEN = 'your_token';

async function getSeasonStages(seasonId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/stages?api_token=${API_TOKEN}&filters=stageSeasons:${seasonId}&order=asc`
  );
  const { data } = await response.json();
  return data;
}

import requests

API_TOKEN = "your_token"

def get_season_stages(season_id):
    url = "https://api.sportmonks.com/v3/motorsport/stages"
    params = {
        "api_token": API_TOKEN,
        "filters": f"stageSeasons:{season_id}",
        "order": "asc"
    }
    response = requests.get(url, params=params)
    return response.json()["data"]

stages = get_season_stages(25273)
for stage in stages:
    status = "Finished" if stage["finished"] else "Upcoming"
    print(f"Round {stage['sort_order']}: {stage['name']} ({status})")

<?php
function getSeasonStages(string $apiToken, int $seasonId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/stages
           ?api_token={$apiToken}&filters=stageSeasons:{$seasonId}&order=asc";
    $response = json_decode(file_get_contents($url), true);
    return $response['data'];
}

Get all sessions for a race weekend

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

def get_stage_sessions(stage_id):
    url = f"https://api.sportmonks.com/v3/motorsport/stages/{stage_id}"
    params = {
        "api_token": API_TOKEN,
        "include": "fixtures"
    }
    response = requests.get(url, params=params)
    stage = response.json()["data"]
    return sorted(stage["fixtures"], key=lambda f: f["starting_at"])

<?php
function getStageSessions(string $apiToken, int $stageId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/stages/{$stageId}
            ?api_token={$apiToken}&include=fixtures";
    $response = json_decode(file_get_contents($url), true);
    $fixtures = $response['data']['fixtures'];
    usort($fixtures, fn($a, $b) => strcmp($a['starting_at'], $b['starting_at']));
    return $fixtures;
}

Find the current active race weekend

def get_current_stage(season_id):
    stages = get_season_stages(season_id)
    return next((s for s in stages if s["is_current"]), None)

async function getCurrentStage(seasonId) {
  const stages = await getSeasonStages(seasonId);
  return stages.find(s => s.is_current) ?? null;
}

Common pitfalls

Using the Schedule endpoint when you need includes. The Schedule endpoint returns a denormalised view of stages and fixtures together, but has no include options. If you need to attach results, lineups, or venue details to fixtures within a weekend, query the stage with &include=fixtures first, then enrich individual fixtures via the Fixtures endpoint.

Confusing sort_order with id. sort_order is the round number within the season (1, 2, 3...). id is the unique database ID of the stage. Use sort_order for display and sorting, id for API lookups.

finished returns a boolean, is_current also returns a boolean. Both are true booleans on the Stage entity (unlike is_current on Season which returns an integer). Check the entity page for the specific type of each field before writing comparison logic.

type_id requires a separate lookup. The stage type (e.g. race weekend vs test session) is an integer ID that maps to a type entity. Include type to get the human-readable label, or fetch all types once and cache them locally.

Common errors

Status

Likely cause

401

Missing or invalid api_token

404

The stage_id does not exist or is not in your subscription

FAQ

What is the difference between a stage and a fixture? A stage is the race weekend as a whole. A fixture is a single session within that weekend (e.g. Practice 1 or the Race). A stage contains multiple fixtures.

How do I find a stage ID if I only know the race name or round number? Query all stages for the season with stageSeasons filter, then match on name or sort_order.

Does each season always start at sort_order 1? Yes. sort_order reflects the round number within the season, starting at 1.

How do I tell if a weekend has a sprint race? Fetch the stage with &include=fixtures and check the fixture names. A sprint weekend will include a "Sprint Qualifying" and "Sprint" fixture in addition to the standard sessions.

Last updated 11 days ago

Was this helpful?