🔮Premium Expected Lineups

🤝 Partner Add-on Required

Premium Expected Lineups requires the Expected Lineups add-on (EUR 199/month)

Available on Growth, Pro, and Enterprise plans. Not available on Starter or legacy plans. Official lineups (published roughly 1 hour before kickoff) are included in all plans at no extra cost. View pricing →

Premium Expected Lineups gives you human-curated predictions of a team's starting eleven and bench, hours before the official lineup is released. This tutorial covers both ways to retrieve it, how to work with the response, and how it differs from the free predictedLineups include.

When to use this

Premium Expected Lineups is built for use cases where being early and being accurate both matter:

• Fantasy football - surface likely starters while squads are still being finalised

• Betting platforms - feed pre-match markets and odds explanations with a reliable early lineup

• Media and analysis - publish lineup previews and tactical breakdowns ahead of the official announcement

• Club and scouting tools - anticipate an opponent's setup for pre-match analysis

Unlike the free predictedLineups include, which is generated automatically from historical data, Premium Expected Lineups is human-curated: analysts monitor team news, press conferences, and injury reports to build the prediction. That's the trade-off you're paying for - more accurate, more current, but not free.

	predictedLineups (free)	Premium Expected Lineups
Availability	All plans (legacy excluded)	Growth and above, add-on required
Data source	Historical data and previous lineups	Human-curated: news, press conferences, injury reports
Update method	Automated	Manually reviewed
Best for	General pre-match display	Fantasy, betting, and time-sensitive use cases

If you only need a rough early estimate for a general-purpose match page, predictedLineups may be all you need. If your product depends on lineup accuracy close to kickoff, Premium Expected Lineups is the better fit.

How to retrieve the data

There are two ways to pull Premium Expected Lineups, depending on whether you're already working with a fixture or want a standalone feed by team or player.

Option 1: the expectedLineups include

If you're already retrieving a fixture or livescore, attach expectedLineups as an include:

GET https://api.sportmonks.com/v3/football/fixtures/{fixture_id}
?api_token=YOUR_TOKEN&include=expectedLineups

This is the simplest option for match-centre and pre-match preview pages, since it arrives alongside the rest of the fixture data in a single call.

Option 2: the standalone endpoints

For dashboards, widgets, or analytics tools that need expected lineups across many fixtures without pulling full fixture objects each time, use the two dedicated endpoints:

By player:

GET https://api.sportmonks.com/v3/football/expected-lineups/players/{player_id}
?api_token=YOUR_TOKEN&include=fixture,team,expected

By team:

GET https://api.sportmonks.com/v3/football/expected-lineups/teams/{team_id}
?api_token=YOUR_TOKEN&include=fixture,team,expected

Both endpoints support pagination and up to 3 levels of nested includes. Available include options are type, fixture, player, and team.

JavaScript

const API_TOKEN = "YOUR_TOKEN";
const PLAYER_ID = 37526530;

async function getExpectedLineup(playerId) {
  const url = `https://api.sportmonks.com/v3/football/expected-lineups/players/${playerId}`;
  const params = new URLSearchParams({
    api_token: API_TOKEN,
    include: "fixture,team,expected"
  });

  const response = await fetch(`${url}?${params}`);
  const data = await response.json();
  return data.data;
}

Python

import requests

api_token = "YOUR_TOKEN"
player_id = 37526530

url = f"https://api.sportmonks.com/v3/football/expected-lineups/players/{player_id}"

params = {
    "api_token": api_token,
    "include": "fixture,team,expected"
}

response = requests.get(url, params=params)
response.raise_for_status()

data = response.json()
expected_lineup = data["data"]

PHP

<?php
$apiToken = "YOUR_TOKEN";
$playerId = 37526530;

$url = "https://api.sportmonks.com/v3/football/expected-lineups/players/{$playerId}";
$params = http_build_query([
    "api_token" => $apiToken,
    "include" => "fixture,team,expected"
]);

$response = file_get_contents("{$url}?{$params}");
$data = json_decode($response, true);
$expectedLineup = $data["data"];

Working with the data

A response entry looks like this:

{
  "id": 1,
  "sport_id": 1,
  "fixture_id": 19347797,
  "player_id": 37526530,
  "team_id": 3285,
  "formation_field": null,
  "position_id": null,
  "detailed_position_id": null,
  "type_id": 77615,
  "formation_position": null,
  "player_name": "Hlynur Freyr Karlsson",
  "jersey_number": 2
}

Field	Description	Type
id	Unique ID of the expected lineup entry	integer
sport_id	Sport ID	integer
fixture_id	The fixture this prediction relates to	integer
player_id	The player in the expected lineup	integer
team_id	The team the player plays for	integer
formation_field	The player's predicted formation field position	integer
position_id	The player's position	integer
detailed_position_id	The player's detailed position	integer
type_id	The type of the expected lineup entry (for example, starter vs bench)	integer
formation_position	The player's predicted formation position	integer
player_name	Name of the player	string
jersey_number	Player's jersey number	integer

Note that type_id here does not work the same way it does on the standard lineups include. Confirmed lineups use type_id 11 for starters and 12 for substitutes. Premium Expected Lineups and predictedLineups both return a single repeated type_id (77615 and 111384 respectively) across every entry in their live examples, and neither value appears in the public Types reference.

To confirm whether a prediction has been superseded by the official lineup, check the lineup_confirmed field in the fixture's metadata include. It's false while you're looking at a prediction, and flips to true once the club has officially released their lineup.

Common pitfalls

• No prediction if the player isn't in the squad. If a player isn't listed in the current squad, they won't appear in the expected lineup, even if scouting reports suggest they're a likely starter.

• Rotation-heavy teams are less predictable. Accuracy drops for teams with frequent rotation or tactical experimentation between matches.

• Don't present predictions as confirmed. Always visually distinguish predicted lineups from confirmed ones in your UI. A last-minute injury or tactical change can still invalidate a prediction right up to kickoff.

• This isn't the same feature as xG. Premium Expected Lineups (expectedLineups, /expected-lineups/) is a different feature from Expected Goals (xGFixture, /expected/). The naming is similar; the data isn't.

Advanced usage

Pair with sidelined data. Combine expected lineups with the sidelined include to explain unexpected omissions - a player missing from the predicted XI due to injury or suspension is a much clearer story for your users than an unexplained absence.

Build a polling strategy around lineup_confirmed. For a live pre-match page: poll the fixture with expectedLineups and metadata included, display the prediction while lineup_confirmed is false, and switch your UI to the standard lineups include the moment it flips to true.

Known accuracy by league. Sportmonks publishes rough accuracy figures for Premium Expected Lineups across major competitions: Bundesliga and Serie A around 87%, Eredivisie around 88%, Champions League and Premier League around 84%, and La Liga around 75%. These are useful context for setting expectations with your own users, but treat them as approximate rather than a guarantee.

Common errors

Status	Cause
400	Malformed request - an unsupported parameter or filter was passed. The exact reason is returned in the response body
403	"Not authorized" - the Expected Lineups add-on isn't active on your account, or your plan (Starter/legacy) doesn't include it
429	Rate limit exceeded for your subscription. Check the meta section of any successful response for your current limit
500	Internal error - logged automatically. Contact support if this persists

An unknown player_id or team_id most likely returns a 200 with an empty data array rather than a 404, since these are collection endpoints. Worth a quick live test before publishing rather than assuming.

Check our coverage

See also

Related tutorials

• Predicted Lineups - the free, automated alternative

• Lineups - working with confirmed lineups

• Lineups and formations - displaying formations alongside lineups

Reference

• Premium Expected Lineups endpoint reference

• Plans & pricing

FAQ

Should I use the fixture endpoint or the standalone Premium Expected Lineups endpoints? Use the fixture endpoint with the expectedLineups include when you're already building a match-centre or pre-match preview page and want everything in one call. Use the standalone /expected-lineups/teams/{id} or /expected-lineups/players/{id} endpoints when you need scalable access across many fixtures at once, for example a dashboard or widget tracking a specific team's upcoming matches.

Does Premium Expected Lineups replace the official lineup? No. It's a prediction that exists only until the official lineup is confirmed. Once lineup_confirmed is true on the fixture, use the standard lineups include instead.

Is Premium Expected Lineups available on my plan? It requires the Expected Lineups add-on on Growth, Pro, or Enterprise. It isn't available on Starter or legacy plans. Official (confirmed) lineups remain free on every plan.

How accurate are the predictions? Accuracy varies by league, roughly 75-88% depending on the competition. See Advanced usage above for a per-league breakdown.