How to Use Includes in the Motorsport API

✅ Included in All Plans

The includes system is available at no additional cost.

Plans differ only in leagues and API call limits.

Compare plans →

This guide explains how to use includes in the Motorsport API to enrich responses with related data, and how to keep requests efficient using field selection and nested includes.

When to use this

Use includes when you want to:

• Fetch a fixture and its driver lineup in a single request instead of two

• Retrieve standings with driver names and images attached

• Pull lap data with sector times without a separate request to a type reference endpoint

• Reduce the number of API calls your application makes during a live session

The basics

By default, every endpoint returns only the fields of the base entity. Related data - driver details on a standing, venue data on a fixture, sector times on a lap - is not included unless you ask for it.

The include parameter adds related entities directly to the response:

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

The response now contains a venue object nested inside the fixture, saving a separate call to the venues endpoint.

Syntax rules

Syntax	Purpose	Example
&include=	Add a related entity	&include=venue
;	Separate multiple includes	&include=venue;state
.	Nest an include one level deeper	&include=lineups.driver
:	Select specific fields on an include	&include=lineups.driver:display_name,image_path

Multiple includes in one request:

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

Include depth

Every endpoint specifies a maximum include depth. Exceeding it returns a query complexity error.

Examples from common endpoints:

Endpoint	Max depth
GET Fixture by ID	3
GET Driver Standings by Season ID	2
GET Laps by Fixture ID	2
GET Pitstops by Fixture ID	2
GET Stints by Fixture ID	2
GET Schedule by Season	0

A depth of 2 means you can nest one level deep, for example lineups.driver. A depth of 3 allows lineups.driver.country.

Check the include depth listed on each endpoint's documentation page before building your request.

Practical examples

Fixture with venue and current state

const response = await fetch(
  `https://api.sportmonks.com/v3/motorsport/fixtures/19408487
?api_token=${API_TOKEN}&include=venue;state`
);

Driver standings with driver name and image

const response = await fetch(
  `https://api.sportmonks.com/v3/motorsport/standings/drivers/seasons/25273
?api_token=${API_TOKEN}&include=participant`
);

const { data } = await response.json();
const sorted = data.sort((a, b) => a.position - b.position);

sorted.forEach(entry => {
  console.log(
    `${entry.position}. ${entry.participant.display_name} - ${entry.points} pts`
  );
});

Laps with full sector timing

// The details include adds lap duration and sector times
const response = await fetch(
  `https://api.sportmonks.com/v3/motorsport/fixtures/19408487/laps
?api_token=${API_TOKEN}&include=details`
);

The details include on laps, pitstops, and stints returns type-keyed data. Resolve type IDs via the Results and Live Data Type Reference.

Live session with results and latest laps

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

Fixture lineup with driver nationality (depth 3)

// lineups → driver → country is 2 hops, within the depth-3 limit
const response = await fetch(
  `https://api.sportmonks.com/v3/motorsport/fixtures/19408487
?api_token=${API_TOKEN}&include=lineups.driver;lineups.driver.country`
);

Field selection

If you only need specific fields from an include, add :field1,field2 after the include name. This reduces response size and improves speed on large payloads.

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

The response returns only display_name and image_path on each driver, and only name and image_path on each country, rather than the full entity.

You can also select fields on the base entity itself:

GET https://api.sportmonks.com/v3/motorsport/fixtures/19408487
?api_token={your_token}&select=name,starting_at

Common pitfalls

Not all includes are available on every endpoint. Each endpoint page lists its supported includes under "Include options". Requesting an unsupported include does not return an error - it is silently ignored. If expected data is missing, check the endpoint's include list first.

Depth limits apply to the chain, not each include independently. lineups.driver.country counts as depth 2. Adding a third level like lineups.driver.country.continent would exceed a depth-3 limit.

The details include behaves differently from entity includes. On laps, pitstops, and stints, details returns an array of type-keyed objects rather than a single nested entity. You need to look up type_id values in the Results and Live Data Type Reference to interpret each entry.

Heavy includes increase query complexity. If a request returns a 422 complexity error, remove includes one at a time to find the combination that exceeds the threshold. The query complexity score for each include is listed on the endpoint's documentation page.

The Schedule endpoint accepts no includes. GET Schedule by Season has an include depth of 0. Venue and fixture data is already pre-embedded in the response.

See also

Reference

• Request Options

• Query Complexity

• Results and Live Data Type Reference

Related tutorials

• Retrieving Results

Related entities

• Fixture

• Lap

• Pitstop

• Stint

FAQ

What happens if I request an unsupported include? It is silently ignored. The response returns as if the include was not specified. Check the endpoint's "Include options" list if expected data is missing.

Can I use includes and field selection together? Yes. &include=lineups.driver:display_name&select=name,starting_at is valid - field selection on the base entity and field selection on an include can be combined in the same request.

Does using more includes count against my rate limit? Each API call counts as one request regardless of how many includes it contains. However, complex includes may exceed the query complexity threshold, returning a 422 error rather than a rate limit error.

Is semicolon or comma the separator for multiple includes? Semicolon (;). Commas are used only for field selection within a single include, e.g. include=lineups.driver:display_name,image_path.