> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/enrich-your-response/how-to-use-includes-in-the-motorsport-api.md).

# 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 →](https://www.sportmonks.com/football-api/plans-pricing/)

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:

```http
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

```javascript
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

```javascript
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

```javascript
// 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](https://docs.sportmonks.com/v3/motorsport-api/welcome/results-and-live-data-type-reference).

#### Live session with results and latest laps

```javascript
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)

```javascript
// 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.

```http
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:

```http
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](https://docs.sportmonks.com/v3/motorsport-api/welcome/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](https://docs.sportmonks.com/v3/motorsport-api/welcome/request-options)
* [Query Complexity](https://docs.sportmonks.com/v3/motorsport-api/welcome/query-complexity)
* [Results and Live Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/results-and-live-data-type-reference)

**Related tutorials**

* [Retrieving Results](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/retrieving-results)

**Related entities**

* [Fixture](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/fixture.md)
* [Lap](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/lap.md)
* [Pitstop](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/pitstop.md)
* [Stint](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/stint.md)

### 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`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/enrich-your-response/how-to-use-includes-in-the-motorsport-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.