Lineups endpoint

Football Lineups API

Fetch confirmed starting elevens, substitutes, formations, and player positions for each match.

Quick answer

The football lineups API returns the starting XI, bench, formation, and per-player positions for a match once lineups are confirmed, joined to player and team IDs.

GET /football/matches/{match_id}/lineups

Example request

const res = await fetch(
  "https://api.thestatsapi.com/api/football/matches/{match_id}/lineups",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data);

JSON response

{
  "data": {
    "match_id": "mt_10481",
    "home": {
      "team": "Manchester City",
      "formation": "4-3-3",
      "starting_xi": [
        { "player_id": 201, "name": "Ederson", "position": "GK", "number": 31 },
        { "player_id": 1101, "name": "Erling Haaland", "position": "ST", "number": 9 }
      ],
      "substitutes": [
        { "player_id": 233, "name": "Julian Alvarez", "position": "ST", "number": 19 }
      ]
    }
  }
}

Key response fields

formation

Team shape, e.g. 4-3-3.

starting_xi

Confirmed starters with positions and numbers.

substitutes

Named bench players.

player_id

Join to the player stats endpoint.

What you can build with the Football Lineups API

Pre-match lineup graphics

Fantasy lineup confirmation alerts

Formation and tactics visualisations

Team news content

The Football Lineups API is part of TheStatsAPI, a single REST API covering 1,000+ football competitions with fixtures, results, standings, player and match stats, odds, and xG. Plans start at $50/month with a 7-day free trial and every endpoint included.