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

Notation	Depth	Valid?
fixtures	1	✅
fixtures.lineups	2	✅
lineups.player.statistics	3	✅
season.fixtures.lineups.player	4	❌

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