> 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/endpoints-and-entities/endpoints/premium-expected-lineups.md).

# Premium Expected Lineups

{% hint style="info" %}
**🤝 Partner Add-on Required**

Premium Expected Lineups requires the **Expected Lineups add-on** (EUR 199/month), powered by FootballFeeds.

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

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:

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

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

**By team:**

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

{% tabs %}
{% tab title="JavaScript" %}

```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;
}
```

{% endtab %}

{% tab title="Python" %}

```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"]
```

{% endtab %}

{% tab title="PHP" %}

```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"];
```

{% endtab %}
{% endtabs %}

<figure><img src="/files/8hujn7i3nDmgbzoLWMD0" alt=""><figcaption></figcaption></figure>

### Working with the data

A response entry looks like this:

```json
{
  "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
}
```

<table data-search="false"><thead><tr><th>Field</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique ID of the expected lineup entry</td><td>integer</td></tr><tr><td><code>sport_id</code></td><td>Sport ID</td><td>integer</td></tr><tr><td><code>fixture_id</code></td><td>The fixture this prediction relates to</td><td>integer</td></tr><tr><td><code>player_id</code></td><td>The player in the expected lineup</td><td>integer</td></tr><tr><td><code>team_id</code></td><td>The team the player plays for</td><td>integer</td></tr><tr><td><code>formation_field</code></td><td>The player's predicted formation field position</td><td>integer</td></tr><tr><td><code>position_id</code></td><td>The player's position</td><td>integer</td></tr><tr><td><code>detailed_position_id</code></td><td>The player's detailed position</td><td>integer</td></tr><tr><td><code>type_id</code></td><td>The type of the expected lineup entry (for example, starter vs bench)</td><td>integer</td></tr><tr><td><code>formation_position</code></td><td>The player's predicted formation position</td><td>integer</td></tr><tr><td><code>player_name</code></td><td>Name of the player</td><td>string</td></tr><tr><td><code>jersey_number</code></td><td>Player's jersey number</td><td>integer</td></tr></tbody></table>

{% hint style="info" %}
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.&#x20;
{% endhint %}

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.

{% hint style="warning" %}
[**Check our coverage** ](https://docs.google.com/spreadsheets/d/1vNRIZEi6sUDhhbxrcewMCV-x7PWjaZ64oLOjUBUAmzU/edit?gid=0#gid=0)
{% endhint %}

### See also

**Related tutorials**

* [Predicted Lineups](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/predicted-lineups) - the free, automated alternative
* [Lineups](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/lineups) - working with confirmed lineups
* [Lineups and formations](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/lineups-and-formations) - displaying formations alongside lineups

**Reference**

* [Premium Expected Lineups endpoint reference](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-expected-lineups)
* [Plans & pricing](https://www.sportmonks.com/football-api/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.


---

# 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/endpoints-and-entities/endpoints/premium-expected-lineups.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.