Lineups

This guide shows you how to retrieve the driver lineup for a session - which drivers and teams took part, their car number, grid position, and how to enrich the lineup with full driver and team detail.

When to use this

Use the lineups include when you want to:

Display the starting grid for a race or qualifying session
Build a driver roster for a specific session before results are available
Resolve a driver's name, number, and team from a fixture without a separate drivers lookup
Pair lineup data with results or lineups.details to attach timing and status to each driver

The basics

Lineups are not a standalone endpoint. They are retrieved as an include on a fixture:

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

The base lineup entry looks like this:

{
  "id": 14671697707,
  "sport_id": 2,
  "fixture_id": 19408487,
  "player_id": 37920803,
  "team_id": 276189,
  "position_id": 9730,
  "type_id": 11,
  "grid_position": 16,
  "driver_name": "Lewis Hamilton",
  "driver_number": 44
}

player_id is the driver's ID and matches participant_id on results, laps, pitstops, and stints. driver_number is the car number, not the driver's ID. grid_position is only populated for race-type sessions, since practice and qualifying sessions do not have a starting grid in the same sense.

Enriching with driver and team data

The base lineup entry only gives you driver_name and driver_number as flat strings. To get the full driver entity - image, country, short name, debut metadata - nest the driver include:

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

To get the team as well:

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

To go one level deeper and get the driver's country (depth 3, within the limit on the Fixture endpoint):

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

See How to Use Includes in the Motorsport API for the full depth-limit table per endpoint.

Combining lineups with results and details

The lineup itself does not carry timing or status. Pair it with results for position, gap, and tyre data:

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

For the full set of session-level driver data in one nested object - points, laps, pitstops, fastest lap, status - use lineups.details instead of results. This is the richer alternative covered in Retrieving results:

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

Working with the data

Build a starting grid

const API_TOKEN = 'your_token';
const FIXTURE_ID = 19408487;

const response = await fetch(
  `https://api.sportmonks.com/v3/motorsport/fixtures/${FIXTURE_ID}?api_token=${API_TOKEN}&include=lineups.driver;lineups.team`
);
const { data: fixture } = await response.json();

const grid = fixture.lineups
  .filter(entry => entry.grid_position !== null)
  .sort((a, b) => a.grid_position - b.grid_position)
  .map(entry => ({
    position: entry.grid_position,
    driver: entry.driver.display_name,
    number: entry.driver_number,
    team: entry.team.name
  }));

console.log(grid);

import requests

API_TOKEN = "your_token"
FIXTURE_ID = 19408487

url = f"https://api.sportmonks.com/v3/motorsport/fixtures/{FIXTURE_ID}"
params = {
    "api_token": API_TOKEN,
    "include": "lineups.driver;lineups.team"
}

response = requests.get(url, params=params)
fixture = response.json()["data"]

grid = sorted(
    (entry for entry in fixture["lineups"] if entry["grid_position"] is not None),
    key=lambda entry: entry["grid_position"]
)

for entry in grid:
    driver = entry["driver"]["display_name"]
    number = entry["driver_number"]
    team = entry["team"]["name"]
    print(f"{entry['grid_position']}. {driver} (#{number}) - {team}")

<?php
$apiToken = 'your_token';
$fixtureId = 19408487;

$url = "https://api.sportmonks.com/v3/motorsport/fixtures/{$fixtureId}?api_token={$apiToken}&include=lineups.driver;lineups.team";
$response = json_decode(file_get_contents($url), true);
$fixture = $response['data'];

$grid = array_filter($fixture['lineups'], fn($entry) => $entry['grid_position'] !== null);
usort($grid, fn($a, $b) => $a['grid_position'] <=> $b['grid_position']);

foreach ($grid as $entry) {
    echo "{$entry['grid_position']}. {$entry['driver']['display_name']} (#{$entry['driver_number']}) - {$entry['team']['name']}\n";
}

Resolve a driver from a result entry

When working with the results include separately from lineups, you will often need to match a participant_id back to a driver name. Pre-load the lineup once per fixture and build a lookup:

function buildDriverLookup(lineups) {
  return new Map(
    lineups.map(entry => [entry.player_id, {
      name: entry.driver_name,
      number: entry.driver_number,
      teamId: entry.team_id
    }])
  );
}

const driverLookup = buildDriverLookup(fixture.lineups);
const driver = driverLookup.get(resultEntry.participant_id);

def build_driver_lookup(lineups):
    return {
        entry["player_id"]: {
            "name": entry["driver_name"],
            "number": entry["driver_number"],
            "team_id": entry["team_id"],
        }
        for entry in lineups
    }

driver_lookup = build_driver_lookup(fixture["lineups"])
driver = driver_lookup.get(result_entry["participant_id"])

This avoids a second API call per result entry, since the lineup is already loaded for the fixture.

Common pitfalls

grid_position is null for non-race sessions. Practice and qualifying sessions do not populate this field the same way a race does. Check for null before sorting or displaying a grid for these session types.

player_id on a lineup entry matches participant_id elsewhere, not id. When joining lineup data with results, laps, pitstops, or stints, match on lineups[].player_id against participant_id in those responses. They are the same driver ID under different field names depending on the entity.

driver_name and driver_number are denormalised flat fields, not the full driver entity. If you need the driver's image, country, or short name, you must add the lineups.driver nested include. The flat fields exist for convenience when you only need a display name.

Team data is not included by default. team_id is present on the base lineup entry, but the team name, colour, and logo require the lineups.team nested include.

Mixing lineups.details and results in the same request adds unnecessary payload. Both return overlapping driver-level data. Use results for a lighter response with the most common fields, or lineups.details when you need the full type set. Avoid requesting both together unless you specifically need fields only available in one.

Common errors

Status

Likely cause

401

Missing or invalid api_token

404

The fixture_id does not exist

422

Query complexity exceeded - remove nested includes such as lineups.driver.country

FAQ

Can I get lineups without fetching the whole fixture? No. Lineups are only available as a nested include on a fixture (or anywhere fixtures themselves are included, such as a season or stage). There is no standalone lineups endpoint.

Does the lineup change after the session starts? The lineup for a race is generally fixed at the start, but driver changes (rare, due to injury or disqualification before the session begins) are reflected if you re-fetch the fixture.

Why is grid_position different from position_id? grid_position is the starting position for the session. position_id is an internal classification field unrelated to finishing or starting order. Use results or lineups.details with the POSITION type for live or finishing position instead.

How do I get the lineup for an entire season at once? Nest the include further from the season level: &include=fixtures.lineups.driver. Be mindful of the include depth limit on the seasons endpoint before doing this for a full season of fixtures in one call.

Last updated 13 days ago

Was this helpful?