> 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/tutorials-and-guides/tutorials/enrich-your-response/nested-includes-reference.md).

# Nested includes reference

Nested includes allow you to retrieve related data in a single API request by chaining multiple include parameters together. This documentation contains only validated nested includes from the Sportmonks API specification.

### Syntax

Use dot notation to chain includes together:

```
?include=parent.child.grandchild
```

**Examples:**

* `fixtures.participants` : Get fixture with participant details
* `lineups.player.country` : Get lineups with player and country details
* `season.fixtures.lineups` : Get season with fixtures and their lineups

***

### Critical limitations

There are two separate constraints to be aware of, and both apply simultaneously.

**1. Nesting depth:** how many dot-levels deep a single include chain can go. The maximum is 3 levels for most endpoints.

| Level | Example                          | Valid?          |
| ----- | -------------------------------- | --------------- |
| 1     | `fixtures`                       | ✅               |
| 2     | `fixtures.league`                | ✅               |
| 3     | `season.fixtures.lineups`        | ✅               |
| 4     | `season.fixtures.lineups.player` | ❌ Exceeds limit |

**2. Include count:** how many separate include parameters you can pass in a single request. When the Sportmonks docs say "you can use a total of `3` nested includes on this endpoint", this refers to the number of comma-separated includes, not the depth. For example:

```
?include=fixtures.league,fixtures.participants,fixtures.venue
```

That request uses 3 includes (the maximum on many endpoints). Adding a fourth comma-separated include would exceed the limit, regardless of how deeply nested each one is.

Both limits must be respected at the same time.

### Best practices

**✅ DO:**

* Only include the data you actually need
* Use separate requests for deeper nesting
* Check response sizes with nested includes
* Cache responses appropriately

**❌ DON'T:**

* Chain more than 3 levels
* Include everything "just in case"
* Assume all parent.child chains are valid

### Complete nested includes by domain

#### 1. Core match data

**Fixtures**

| Include                    | Description          |
| -------------------------- | -------------------- |
| `fixtures.sport`           | Sport details        |
| `fixtures.round`           | Round details        |
| `fixtures.stage`           | Stage details        |
| `fixtures.group`           | Group details        |
| `fixtures.aggregate`       | Aggregate details    |
| `fixtures.league`          | League details       |
| `fixtures.season`          | Season details       |
| `fixtures.venue`           | Venue details        |
| `fixtures.state`           | Match state          |
| `fixtures.weatherReport`   | Weather information  |
| `fixtures.lineups`         | Team lineups         |
| `fixtures.timeline`        | Match timeline       |
| `fixtures.events`          | Match events         |
| `fixtures.comments`        | Match comments       |
| `fixtures.trends`          | Match trends         |
| `fixtures.statistics`      | Match statistics     |
| `fixtures.periods`         | Period data          |
| `fixtures.participants`    | Participating teams  |
| `fixtures.odds`            | Odds data            |
| `fixtures.premiumOdds`     | Premium odds         |
| `fixtures.inplayOdds`      | In-play odds         |
| `fixtures.postmatchNews`   | Post-match news      |
| `fixtures.prematchNews`    | Pre-match news       |
| `fixtures.metadata`        | Fixture metadata     |
| `fixtures.predictions`     | Match predictions    |
| `fixtures.referees`        | Referee details      |
| `fixtures.formations`      | Team formations      |
| `fixtures.ballCoordinates` | Ball coordinate data |
| `fixtures.sidelined`       | Sidelined players    |
| `fixtures.scores`          | Score data           |

**Inplay (Live matches)**

| Include                  | Description          |
| ------------------------ | -------------------- |
| `inplay.sport`           | Sport details        |
| `inplay.round`           | Round details        |
| `inplay.stage`           | Stage details        |
| `inplay.group`           | Group details        |
| `inplay.aggregate`       | Aggregate details    |
| `inplay.league`          | League details       |
| `inplay.season`          | Season details       |
| `inplay.venue`           | Venue details        |
| `inplay.state`           | Match state          |
| `inplay.weatherReport`   | Weather information  |
| `inplay.lineups`         | Team lineups         |
| `inplay.events`          | Match events         |
| `inplay.timeline`        | Match timeline       |
| `inplay.comments`        | Match comments       |
| `inplay.trends`          | Match trends         |
| `inplay.statistics`      | Match statistics     |
| `inplay.periods`         | Period data          |
| `inplay.participants`    | Participating teams  |
| `inplay.odds`            | Odds data            |
| `inplay.premiumOdds`     | Premium odds         |
| `inplay.inplayOdds`      | In-play odds         |
| `inplay.prematchNews`    | Pre-match news       |
| `inplay.postmatchNews`   | Post-match news      |
| `inplay.metadata`        | Fixture metadata     |
| `inplay.tvStations`      | TV broadcast info    |
| `inplay.predictions`     | Match predictions    |
| `inplay.referees`        | Referee details      |
| `inplay.formations`      | Team formations      |
| `inplay.ballCoordinates` | Ball coordinate data |
| `inplay.sidelined`       | Sidelined players    |
| `inplay.scores`          | Score data           |
| `inplay.xGfixture`       | Expected goals data  |
| `inplay.currentPeriod`   | Current period info  |

**Latest (Recent matches)**

| Include                  | Description          |
| ------------------------ | -------------------- |
| `latest.sport`           | Sport details        |
| `latest.round`           | Round details        |
| `latest.stage`           | Stage details        |
| `latest.group`           | Group details        |
| `latest.aggregate`       | Aggregate details    |
| `latest.league`          | League details       |
| `latest.season`          | Season details       |
| `latest.coaches`         | Coach details        |
| `latest.tvStations`      | TV broadcast info    |
| `latest.venue`           | Venue details        |
| `latest.state`           | Match state          |
| `latest.weatherReport`   | Weather information  |
| `latest.lineups`         | Team lineups         |
| `latest.events`          | Match events         |
| `latest.timeline`        | Match timeline       |
| `latest.comments`        | Match comments       |
| `latest.trends`          | Match trends         |
| `latest.statistics`      | Match statistics     |
| `latest.periods`         | Period data          |
| `latest.participants`    | Participating teams  |
| `latest.odds`            | Odds data            |
| `latest.premiumOdds`     | Premium odds         |
| `latest.inplayOdds`      | In-play odds         |
| `latest.prematchNews`    | Pre-match news       |
| `latest.postmatchNews`   | Post-match news      |
| `latest.metadata`        | Fixture metadata     |
| `latest.sidelined`       | Sidelined players    |
| `latest.predictions`     | Match predictions    |
| `latest.referees`        | Referee details      |
| `latest.formations`      | Team formations      |
| `latest.ballCoordinates` | Ball coordinate data |
| `latest.scores`          | Score data           |
| `latest.xGFixture`       | Expected goals data  |
| `latest.pressure`        | Pressure data        |

#### 2. Competition structure

**League**

| Include                 | Description          |
| ----------------------- | -------------------- |
| `league.country`        | Country details      |
| `league.sport`          | Sport details        |
| `league.stages`         | All stages           |
| `league.latest`         | Latest fixtures      |
| `league.upcoming`       | Upcoming fixtures    |
| `league.inplay`         | Live fixtures        |
| `league.today`          | Today's fixtures     |
| `league.currentSeason`  | Current season       |
| `league.seasons`        | All seasons          |
| `league.season.fixture` | Fixtures in a season |
| `league.season.stages`  | Stages in a season   |
| `league.season.rounds`  | Rounds in a season   |
| `league.stages.fixture` | Fixtures in stages   |
| `league.stages.groups`  | Groups within stages |

**Season**

| Include                           | Description                      |
| --------------------------------- | -------------------------------- |
| `season.stages`                   | All stages                       |
| `season.rounds`                   | All rounds                       |
| `season.leagues`                  | Associated leagues               |
| `season.stages.rounds`            | Rounds within stages             |
| `season.rounds.stage`             | Stage for each round             |
| `season.fixtures`                 | All fixtures                     |
| `season.fixtures.round`           | Round for each fixture           |
| `season.fixtures.stage`           | Stage for each fixture           |
| `season.fixtures.group`           | Group for each fixture           |
| `season.fixtures.aggregate`       | Aggregate data                   |
| `season.fixtures.league`          | League for each fixture          |
| `season.fixtures.coaches`         | Coaches for each fixture         |
| `season.fixtures.tvStations`      | TV stations for each fixture     |
| `season.fixtures.venue`           | Venue for each fixture           |
| `season.fixtures.state`           | State for each fixture           |
| `season.fixtures.weatherReport`   | Weather for each fixture         |
| `season.fixtures.lineups`         | Lineups for each fixture         |
| `season.fixtures.events`          | Events for each fixture          |
| `season.fixtures.timeline`        | Timeline for each fixture        |
| `season.fixtures.comments`        | Comments for each fixture        |
| `season.fixtures.trends`          | Trends for each fixture          |
| `season.fixtures.statistics`      | Statistics for each fixture      |
| `season.fixtures.periods`         | Periods for each fixture         |
| `season.fixtures.participants`    | Participants for each fixture    |
| `season.fixtures.odds`            | Odds for each fixture            |
| `season.fixtures.premiumOdds`     | Premium odds for each fixture    |
| `season.fixtures.inplayOdds`      | In-play odds for each fixture    |
| `season.fixtures.prematchNews`    | Pre-match news for each fixture  |
| `season.fixtures.postmatchNews`   | Post-match news for each fixture |
| `season.fixtures.metadata`        | Metadata for each fixture        |
| `season.fixtures.sidelined`       | Sidelined players per fixture    |
| `season.fixtures.predictions`     | Predictions for each fixture     |
| `season.fixtures.referees`        | Referees for each fixture        |
| `season.fixtures.formations`      | Formations for each fixture      |
| `season.fixtures.ballCoordinates` | Ball coordinates per fixture     |
| `season.fixtures.scores`          | Scores for each fixture          |
| `season.fixtures.xGFixture`       | xG data for each fixture         |
| `season.fixtures.pressure`        | Pressure data per fixture        |

**Stages (plural)**

| Include               | Description          |
| --------------------- | -------------------- |
| `stages.type`         | Stage type           |
| `stages.season`       | Associated season    |
| `stages.league`       | Associated league    |
| `stages.sport`        | Associated sport     |
| `stages.rounds`       | Rounds in the stage  |
| `stages.currentRound` | Current round        |
| `stages.groups`       | Groups within stages |
| `stages.fixtures`     | Fixtures in stages   |
| `stages.aggregates`   | Aggregate data       |
| `stages.topscorers`   | Top scorers          |
| `stages.statistics`   | Stage statistics     |

**Stage (singular)**

| Include                     | Description                  |
| --------------------------- | ---------------------------- |
| `stage.league`              | Associated league            |
| `stage.season`              | Associated season            |
| `stage.season.rounds`       | Rounds in the season         |
| `stage.sport`               | Associated sport             |
| `stage.rounds`              | Rounds in the stage          |
| `stage.rounds.season`       | Season for each round        |
| `stage.currentRound`        | Current round                |
| `stage.type`                | Stage type                   |
| `stage.fixtures.round`      | Round for each fixture       |
| `stage.fixtures.stage`      | Stage for each fixture       |
| `stage.fixtures.aggregate`  | Aggregate data               |
| `stage.fixtures.league`     | League for each fixture      |
| `stage.fixtures.coaches`    | Coaches for each fixture     |
| `stage.fixtures.tvStations` | TV stations for each fixture |
| `stage.fixtures.venue`      | Venue for each fixture       |
| `stage.aggregates`          | Aggregate data               |
| `stage.topscorers`          | Top scorers                  |
| `stage.statistics`          | Stage statistics             |

**Round**

| Include                | Description           |
| ---------------------- | --------------------- |
| `round.league`         | Associated league     |
| `round.league.country` | Country of the league |
| `round.league.season`  | Season of the league  |
| `round.season`         | Associated season     |
| `round.season.league`  | League for the season |
| `round.season.stages`  | Stages in the season  |
| `round.stage`          | Associated stage      |
| `round.stage.season`   | Season for the stage  |
| `round.fixtures`       | Fixtures in the round |
| `round.statistics`     | Round statistics      |
| `round.sport`          | Associated sport      |

**Aggregate (two-leg matches)**

| Include                   | Description             |
| ------------------------- | ----------------------- |
| `aggregate.league`        | Associated league       |
| `aggregate.season`        | Associated season       |
| `aggregate.season.rounds` | Rounds in the season    |
| `aggregate.season.stages` | Stages in the season    |
| `aggregate.stage`         | Associated stage        |
| `aggregate.stage.rounds`  | Rounds in the stage     |
| `aggregate.stage.season`  | Season for the stage    |
| `aggregate.winner`        | Winner of the aggregate |

#### 3. Teams & participants

**Participants**

| Include                          | Description               |
| -------------------------------- | ------------------------- |
| `participants.country`           | Country details           |
| `participants.country.continent` | Continent of the country  |
| `participants.venue`             | Venue details             |
| `participants.venue.city`        | City of the venue         |
| `participants.coaches`           | Coach details             |
| `participants.players`           | Player list               |
| `participants.players.player`    | Full player details       |
| `participants.latest`            | Latest fixtures           |
| `participants.upcoming`          | Upcoming fixtures         |
| `participants.sidelined`         | Sidelined players         |
| `participants.sidelinedHistory`  | Historical sidelined data |
| `participants.seasons`           | Seasons data              |
| `participants.activeSeasons`     | Active seasons            |
| `participants.rivals`            | Rival teams               |
| `participants.socials`           | Social media links        |
| `participants.trophies`          | Trophies won              |
| `participants.rankings`          | Team rankings             |

**Form**

| Include                     | Description                  |
| --------------------------- | ---------------------------- |
| `form.fixture`              | Fixture details              |
| `form.fixture.participants` | Participants for the fixture |
| `form.fixture.league`       | League for the fixture       |
| `form.fixture.season`       | Season for the fixture       |
| `form.fixture.venue`        | Venue for the fixture        |
| `form.participant`          | Participant details          |

#### 4. Player data

**Player**

| Include                           | Description                 |
| --------------------------------- | --------------------------- |
| `player.position`                 | Player position             |
| `player.detailedposition`         | Detailed position           |
| `player.country`                  | Player's country            |
| `player.nationality`              | Player's nationality        |
| `player.city`                     | Player's city               |
| `player.lineups`                  | Lineup appearances          |
| `player.lineups.details`          | Lineup details              |
| `player.lineups.details.type`     | Type of lineup detail       |
| `player.lineups.position`         | Position in lineup          |
| `player.lineups.detailedposition` | Detailed position in lineup |
| `player.transfers`                | Transfer history            |
| `player.pendingTransfers`         | Pending transfers           |
| `player.teams`                    | Teams the player belongs to |
| `player.teams.team`               | Full team details           |
| `player.statistics`               | Player statistics           |
| `player.latest`                   | Latest fixtures             |
| `player.metadata`                 | Player metadata             |
| `player.metadata.type`            | Metadata type               |
| `player.trophies`                 | Trophies won                |

**Lineups**

| Include                           | Description                |
| --------------------------------- | -------------------------- |
| `lineups.type`                    | Lineup type                |
| `lineups.position`                | Position                   |
| `lineups.detailedposition`        | Detailed position          |
| `lineups.team`                    | Team details               |
| `lineups.player`                  | Player details             |
| `lineups.player.country`          | Player's country           |
| `lineups.player.city`             | Player's city              |
| `lineups.player.nationality`      | Player's nationality       |
| `lineups.player.transfers`        | Player's transfers         |
| `lineups.player.pendingTransfers` | Player's pending transfers |
| `lineups.player.teams`            | Player's teams             |
| `lineups.player.statistics`       | Player's statistics        |
| `lineups.player.latest`           | Player's latest fixtures   |
| `lineups.player.position`         | Player's position          |
| `lineups.player.detailedPosition` | Player's detailed position |
| `lineups.player.lineups`          | Player's other lineups     |
| `lineups.player.metadata`         | Player's metadata          |
| `lineups.player.trophies`         | Player's trophies          |
| `lineups.fixtures`                | Associated fixtures        |
| `lineups.fixtures.round`          | Round for each fixture     |
| `lineups.details`                 | Lineup details             |
| `lineups.details.type`            | Type of lineup detail      |
| `lineups.xGLineup`                | Expected goals per lineup  |

**ExpectedLineups**

| Include                                   | Description                |
| ----------------------------------------- | -------------------------- |
| `expectedLineups.player`                  | Player details             |
| `expectedLineups.player.detailedposition` | Detailed position          |
| `expectedLineups.player.sport`            | Sport details              |
| `expectedLineups.player.country`          | Player's country           |
| `expectedLineups.player.city`             | Player's city              |
| `expectedLineups.player.nationality`      | Player's nationality       |
| `expectedLineups.player.transfers`        | Player's transfers         |
| `expectedLineups.player.pendingtransfers` | Player's pending transfers |
| `expectedLineups.player.teams`            | Player's teams             |
| `expectedLineups.player.statistics`       | Player's statistics        |
| `expectedLineups.player.latest`           | Player's latest fixtures   |
| `expectedLineups.player.position`         | Player's position          |
| `expectedLineups.player.lineups`          | Player's lineup history    |
| `expectedLineups.player.metadata`         | Player's metadata          |
| `expectedLineups.player.trophies`         | Player's trophies          |
| `expectedLineups.team`                    | Team details               |
| `expectedLineups.team.sports`             | Team's sports              |
| `expectedLineups.team.country`            | Team's country             |
| `expectedLineups.team.venue`              | Team's venue               |
| `expectedLineups.team.coaches`            | Team's coaches             |
| `expectedLineups.team.rivals`             | Team's rivals              |
| `expectedLineups.team.players`            | Team's players             |
| `expectedLineups.team.latest`             | Team's latest fixtures     |
| `expectedLineups.team.upcoming`           | Team's upcoming fixtures   |
| `expectedLineups.team.seasons`            | Team's seasons             |
| `expectedLineups.team.aciveseasons`       | Team's active seasons      |
| `expectedLineups.team.sidelined`          | Team's sidelined players   |
| `expectedLineups.team.sidelinedHistory`   | Historical sidelined data  |
| `expectedLineups.team.statistics`         | Team's statistics          |
| `expectedLineups.team.socials`            | Team's social media        |
| `expectedLineups.team.trophies`           | Team's trophies            |
| `expectedLineups.team.rankings`           | Team's rankings            |
| `expectedLineups.type`                    | Lineup type                |
| `expectedLineups.position`                | Position                   |
| `expectedLineups.detailedposition`        | Detailed position          |

**Transfers (plural)**

| Include                      | Description              |
| ---------------------------- | ------------------------ |
| `transfers.fromTeam`         | Origin team              |
| `transfers.toTeam`           | Destination team         |
| `transfers.type`             | Transfer type            |
| `transfers.position`         | Player position          |
| `transfers.detailedPosition` | Detailed player position |

**Transfer (singular)**

| Include                             | Description                |
| ----------------------------------- | -------------------------- |
| `transfer.player`                   | Player details             |
| `transfer.player.country`           | Player's country           |
| `transfer.player.country.continent` | Continent of the country   |
| `transfer.player.position`          | Player's position          |
| `transfer.player.detailedposition`  | Player's detailed position |
| `transfer.player.city`              | Player's city              |
| `transfer.player.lineups`           | Player's lineups           |
| `transfer.player.lineups.details`   | Player's lineup details    |

**PendingTransfers**

| Include                             | Description              |
| ----------------------------------- | ------------------------ |
| `pendingTransfers.fromTeam`         | Origin team              |
| `pendingTransfers.toTeam`           | Destination team         |
| `pendingTransfers.sport`            | Sport details            |
| `pendingTransfers.player`           | Player details           |
| `pendingTransfers.type`             | Transfer type            |
| `pendingTransfers.position`         | Player position          |
| `pendingTransfers.detailedPosition` | Detailed player position |

**Sidelined**

| Include                 | Description             |
| ----------------------- | ----------------------- |
| `sidelined.sideline`    | Sideline details        |
| `sidelined.participant` | Participant details     |
| `sidelined.player`      | Player details          |
| `sidelined.team`        | Team details            |
| `sidelined.season`      | Season details          |
| `sidelined.type`        | Type of injury/sideline |
| `sidelined.fixture`     | Related fixture         |

#### 5. Match events & timeline

**Events (plural)**

| Include                    | Description         |
| -------------------------- | ------------------- |
| `events.type`              | Event type          |
| `events.period`            | Period details      |
| `events.period.type`       | Type of period      |
| `events.fixture`           | Associated fixture  |
| `events.participant`       | Participant details |
| `events.player`            | Player involved     |
| `events.player.country`    | Player's country    |
| `events.player.team`       | Player's team       |
| `events.player.statistics` | Player's statistics |
| `events.subtype`           | Event subtype       |

**Event (singular)**

| Include               | Description            |
| --------------------- | ---------------------- |
| `event.relatedPlayer` | Related player details |

**Timeline**

| Include                  | Description         |
| ------------------------ | ------------------- |
| `timeline.period`        | Period details      |
| `timeline.type`          | Event type          |
| `timeline.period.type`   | Type of period      |
| `timeline.fixture`       | Associated fixture  |
| `timeline.participant`   | Participant details |
| `timeline.player`        | Player involved     |
| `timeline.coach`         | Coach involved      |
| `timeline.relatedPlayer` | Related player      |
| `timeline.details`       | Event details       |

**Periods**

| Include                   | Description          |
| ------------------------- | -------------------- |
| `periods.statistics`      | Period statistics    |
| `periods.timeline`        | Period timeline      |
| `periods.events`          | Events in the period |
| `periods.fixture`         | Associated fixture   |
| `periods.type`            | Period type          |
| `periods.statistics.type` | Type of statistic    |
| `periods.events.type`     | Type of event        |

**Scores**

| Include              | Description         |
| -------------------- | ------------------- |
| `scores.type`        | Score type          |
| `scores.fixtures`    | Associated fixtures |
| `scores.participant` | Participant details |

**Formations**

| Include                  | Description         |
| ------------------------ | ------------------- |
| `formations.fixture`     | Associated fixture  |
| `formations.participant` | Participant details |

**BallCoordinates**

| Include                   | Description        |
| ------------------------- | ------------------ |
| `ballCoordinates.fixture` | Associated fixture |
| `ballCoordinates.period`  | Period details     |

**Trends**

| Include              | Description         |
| -------------------- | ------------------- |
| `trends.type`        | Trend type          |
| `trends.fixture`     | Associated fixture  |
| `trends.participant` | Participant details |
| `trends.period`      | Period details      |

#### 6. Statistical data

**Statistics**

| Include                  | Description         |
| ------------------------ | ------------------- |
| `statistics.type`        | Statistic type      |
| `statistics.details`     | Statistic details   |
| `statistics.season`      | Season details      |
| `statistics.player`      | Player details      |
| `statistics.coach`       | Coach details       |
| `statistics.position`    | Position details    |
| `statistics.fixture`     | Associated fixture  |
| `statistics.participant` | Participant details |

**ActiveSeasons**

| Include                      | Description          |
| ---------------------------- | -------------------- |
| `activeSeasons.sport`        | Sport details        |
| `activeSeasons.league`       | League details       |
| `activeSeasons.teams`        | Teams in the season  |
| `activeSeasons.stages`       | Stages in the season |
| `activeSeasons.currentStage` | Current stage        |
| `activeSeasons.fixtures`     | Season fixtures      |
| `activeSeasons.groups`       | Groups in the season |
| `activeSeasons.statistics`   | Season statistics    |
| `activeSeasons.topscorers`   | Top scorers          |

**CurrentSeason**

| Include                    | Description          |
| -------------------------- | -------------------- |
| `currentSeason.sport`      | Sport details        |
| `currentSeason.league`     | League details       |
| `currentSeason.teams`      | Teams in the season  |
| `currentSeason.stages`     | Stages in the season |
| `currentSeason.fixtures`   | Season fixtures      |
| `currentSeason.statistics` | Season statistics    |
| `currentSeason.topscorers` | Top scorers          |

**Pressure**

| Include                | Description         |
| ---------------------- | ------------------- |
| `pressure.participant` | Participant details |
| `pressure.fixture`     | Associated fixture  |
| `pressure.team`        | Team details        |

**xGFixture (Expected Goals)**

| Include                 | Description         |
| ----------------------- | ------------------- |
| `xGFixture.type`        | xG type             |
| `xGFixture.participant` | Participant details |
| `xGFixture.fixture`     | Associated fixture  |

#### 7. Contextual information

**Venue**

| Include          | Description           |
| ---------------- | --------------------- |
| `venue.city`     | City details          |
| `venue.country`  | Country details       |
| `venue.fixtures` | Fixtures at the venue |

**Coaches**

| Include               | Description                    |
| --------------------- | ------------------------------ |
| `coaches.country`     | Coach's country                |
| `coaches.teams`       | Teams coached                  |
| `coaches.statistics`  | Coaching statistics            |
| `coaches.nationality` | Coach's nationality            |
| `coaches.trophies`    | Trophies won                   |
| `coaches.fixtures`    | Fixtures coached               |
| `coaches.player`      | Player details (if applicable) |

**Referees**

| Include            | Description        |
| ------------------ | ------------------ |
| `referees.referee` | Referee details    |
| `referees.type`    | Referee type       |
| `referees.fixture` | Associated fixture |

**WeatherReport**

| Include                 | Description        |
| ----------------------- | ------------------ |
| `weatherReport.fixture` | Associated fixture |
| `weatherReport.venue`   | Venue details      |

**TvStations**

| Include                | Description              |
| ---------------------- | ------------------------ |
| `tvStations.fixtures`  | Fixtures being broadcast |
| `tvStations.tvStation` | TV station details       |
| `tvStations.country`   | Country of the broadcast |

**Metadata**

| Include         | Description   |
| --------------- | ------------- |
| `metadata.type` | Metadata type |

**Details**

| Include              | Description           |
| -------------------- | --------------------- |
| `details.type`       | Detail type           |
| `details.statistics` | Associated statistics |

#### 8. Odds & predictions

**Odds**

| Include          | Description        |
| ---------------- | ------------------ |
| `odds.market`    | Odds market        |
| `odds.bookmaker` | Bookmaker details  |
| `odds.fixture`   | Associated fixture |

**PremiumOdds**

| Include                 | Description        |
| ----------------------- | ------------------ |
| `premiumOdds.market`    | Odds market        |
| `premiumOdds.bookmaker` | Bookmaker details  |
| `premiumOdds.fixture`   | Associated fixture |

**InplayOdds**

| Include                | Description        |
| ---------------------- | ------------------ |
| `inplayOdds.bookmaker` | Bookmaker details  |
| `inplayOdds.marker`    | Odds marker        |
| `inplayOdds.fixture`   | Associated fixture |

**Predictions**

| Include               | Description        |
| --------------------- | ------------------ |
| `predictions.type`    | Prediction type    |
| `predictions.fixture` | Associated fixture |
| `predictions.league`  | Associated league  |

#### 9. Media & content

**PrematchNews**

| Include                | Description        |
| ---------------------- | ------------------ |
| `prematchNews.lines`   | News lines/content |
| `prematchNews.league`  | Associated league  |
| `prematchNews.fixture` | Associated fixture |

**PostmatchNews**

| Include                 | Description        |
| ----------------------- | ------------------ |
| `postmatchNews.lines`   | News lines/content |
| `postmatchNews.league`  | Associated league  |
| `postmatchNews.fixture` | Associated fixture |

**Comments**

| Include            | Description        |
| ------------------ | ------------------ |
| `comments.fixture` | Associated fixture |
| `comments.player`  | Associated player  |

#### 10. Geographic & organisational

**Country**

| Include             | Description                |
| ------------------- | -------------------------- |
| `country.continent` | Continent details          |
| `country.leagues`   | Leagues in the country     |
| `country.regions`   | Regions within the country |

**Nationality**

| Include                  | Description        |
| ------------------------ | ------------------ |
| `nationality.continents` | Continents         |
| `nationality.leagues`    | Associated leagues |
| `nationality.regions`    | Associated regions |

**City**

| Include       | Description    |
| ------------- | -------------- |
| `city.region` | Region details |

**Position**

| Include          | Description      |
| ---------------- | ---------------- |
| `position.sport` | Associated sport |

**Trophies**

| Include           | Description    |
| ----------------- | -------------- |
| `trophies.trophy` | Trophy details |
| `trophies.team`   | Team details   |
| `trophies.league` | League details |
| `trophies.season` | Season details |

**Rule**

| Include     | Description |
| ----------- | ----------- |
| `rule.type` | Rule type   |

### Common patterns & use cases

**Pattern 1: Basic match information**

```
?include=fixtures.league,fixtures.participants,fixtures.venue
```

Gets fixture with league, teams, and venue (all depth 2).

**Pattern 2: Match with events and players**

First request:

```
?include=fixtures.events,fixtures.lineups
```

Then make a second request using `events` as the root include to go deeper:

```
?include=events.player.country,events.player.statistics
```

**Pattern 3: Season fixtures with details**

```
?include=season.fixtures.lineups,season.fixtures.participants,season.fixtures.venue
```

This uses depth-3 nesting on the season includes.

**Pattern 4: Detailed player information**

```
?include=lineups.player.country,lineups.player.statistics,lineups.player.teams
```

The `lineups` include supports depth-3 nesting for player details.

**Pattern 5: Team squad overview**

```
?include=participants.players.player,participants.coaches,participants.venue.city
```

Gets team with players and venue details (depth 3).

**Pattern 6: League structure**

```
?include=league.currentSeason,league.stages.fixture
```

Gets league with season and stage fixtures (depth 3).

### Depth calculation quick reference

<table><thead><tr><th width="307.4000244140625">Notation</th><th>Depth</th><th>Valid?</th></tr></thead><tbody><tr><td><code>fixtures</code></td><td>1</td><td>✅</td></tr><tr><td><code>fixtures.lineups</code></td><td>2</td><td>✅</td></tr><tr><td><code>lineups.player.statistics</code></td><td>3</td><td>✅</td></tr><tr><td><code>season.fixtures.lineups.player</code></td><td>4</td><td>❌</td></tr></tbody></table>

### Strategy for deep data

If you need depth-4+ data, split into two requests:

1. First request: `?include=season.fixtures.lineups`
2. Extract lineup IDs from the response
3. Second request using `lineups` as the root include: `?include=lineups.player.statistics`

### Performance tips

* **Only request what you need**: every include increases response size
* **Start from the right root**: querying `lineups` directly is more efficient than `fixtures.lineups` when you need player details
* **Cache aggressively**: nested responses can be large
* **Monitor response times**: depth-2 and depth-3 includes can be slower

### Entities with no nested includes

The following entities have no available nested includes:

| Entity             | Notes              |
| ------------------ | ------------------ |
| `currentPeriod`    | No nested includes |
| `detailedPosition` | No nested includes |


---

# 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/tutorials-and-guides/tutorials/enrich-your-response/nested-includes-reference.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.