Match lineups
A
GET
/v1/matches/{id}/lineups
Formation, starting eleven, substitutions and minutes played
Formation, the starting eleven with shirt numbers and grid positions, the substitutes and the coach, for each side. substitutions lists every change in match order: the minute (90+2 as given), player_off and player_on. appearances lists every player who took part, the starters and each substitute who came on, with minute_on, minute_off and minutes_played, worked out from the substitutions: normal time counts as 90 and extra time as 120, with added time where the minute gives it. Both are null where the competition publishes no substitutions. Grid positions are row and column, counting from the goalkeeper out, so a shape can be drawn without guessing at it. Formation also comes back on the match itself, which is the field to filter and group by.
Plan
This endpoint needs Archive.
Calling it on a lower plan returns a 403 naming the plan it needs and
a link to pricing, never a bare refusal.
Parameters
match_id
string
path
required
The match id. Stable across re-imports: what you store today still resolves later. e.g.
mt_1JK5QJ9
Returns
data.match_id
string
Our id for the match. Stable: what you store today still resolves later.
data.home_team_name
string
The home side's name.
data.away_team_name
string
The away side's name.
data.kickoff_utc
integer
Kickoff, as a UTC timestamp.
data.home_formation
empty in this example
Home formation.
data.away_formation
empty in this example
Away formation.
data.lineups
list
Lineups.
data.lineups[].team_name
string
The club's name.
data.lineups[].formation
string
Formation.
data.lineups[].coach_name
string
Coach name.
data.lineups[].starting_xi
list
Starting xi.
data.lineups[].substitutes
list
Substitutes.
data.substitutions
list
Substitutions.
data.substitutions[].team_name
string
The club's name.
data.substitutions[].minute
string
Minute.
data.substitutions[].player_off
string
Player off.
data.substitutions[].player_on
string
Player on.
data.appearances
list
Appearances.
data.appearances[].team_name
string
The club's name.
data.appearances[].player_name
string
The player's name.
data.appearances[].started
boolean
Started.
data.appearances[].minute_on
integer
Minute on.
data.appearances[].minute_off
empty in this example
Minute off.
data.appearances[].minutes_played
integer
Minutes played.
meta.data_as_of
string
When the data behind this answer was last brought up to date.
meta.request_id
string
This request's id, to quote to support.
meta.note
string
Note.
Request
curl "https://api.footballsoccerapi.com/v1/matches/mt_1JK5QJ9/lineups" \ -H "X-API-Key: $FSAPI_KEY"
const res = await fetch("https://api.footballsoccerapi.com/v1/matches/mt_1JK5QJ9/lineups", { headers: { "X-API-Key": process.env.FSAPI_KEY } }); const { data, meta } = await res.json();
import os, requests r = requests.get( "https://api.footballsoccerapi.com/v1/matches/mt_1JK5QJ9/lineups", headers={"X-API-Key": os.environ["FSAPI_KEY"]}, ) data = r.json()["data"]
$ch = curl_init("https://api.footballsoccerapi.com/v1/matches/mt_1JK5QJ9/lineups"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["X-API-Key: {$key}"], ]); $data = json_decode(curl_exec($ch), true)["data"];
Example response
A real row from the archive, fetched when this page rendered. Run it against your own key below.
200 OK
application/json
{
"data": {
"match_id": "mt_0YYGBG4",
"home_team_name": "Juventus W",
"away_team_name": "Lyon W",
"kickoff_utc": 1794427200,
"home_formation": null,
"away_formation": null,
"lineups": [
{
"team_name": "Juventus W",
"formation": "3-4-3",
"coach_name": "Isaac Guerrero",
"starting_xi": [
{
"player_name": "Daniëlle de Jong",
"number": 1,
"position": null,
"position_code": 11,
"rating": 6.9
},
{
"player_name": "Kysha Sylla",
"number": 4,
"position": null,
"position_code": 33,
"rating": 4.9
},
{
"player_name": "Cecilia Salvai",
"number": 23,
"position": null,
"position_code": 35,
"rating": 4.5
},
{
"player_name": "Martina Lenzini",
"number": 71,
"position": null,
"position_code": 37,
"rating": 3.5
},
{
"player_name": "Tatiana Pinto",
"number": 29,
"position": null,
"position_code": 72,
"rating": 6
},
{
"player_name": "Manaka Hayashi",
"number": 30,
"position": null,
"position_code": 74,
"rating": 6
},
{
"player_name": "Eva Schatzer",
"number": 6,
"position": null,
"position_code": 76,
"rating": 5.9
},
{
"player_name": "Estela Carbonell",
"number": 3,
"position": null,
"position_code": 78,
"rating": 5
},
{
"player_name": "Danique Noordman",
"number": 16,
"position": null,
"position_code": 103,
"rating": 5.7
},
{
"player_name": "Alba Redondo",
"number": 20,
"position": null,
"position_code": 105,
"rating": 5.8
},
{
"player_name": "Matilde Pavan",
"number": 19,
"position": null,
"position_code": 107,
"rating": 6.1
}
],
"substitutes": [
{
"player_name": "Júlia Bartel",
"number": 14,
"position": null,
"position_code": null,
"rating": 6.1
},
{
"player_name": "Remina Chiba",
"number": 22,
"position": null,
"position_code": null,
"rating": 6.7
},
{
"player_name": "Amaiur Sarriegi",
"number": 77,
"position": null,
"position_code": null,
"rating": 5.9
},
{
"player_name": "Ornella Graziani",
"number": 28,
"position": null,
"position_code": null,
"rating": 6.4
},
{
"player_name": "Cristina Librán",
"number": 46,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Giulia Martinazzi",
"number": 50,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Larissa Rusek",
"number": 21,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Martina Rosucci",
"number": 8,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Marzia Piermarini",
"number": 41,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Giorgia Bianchi",
"number": 44,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Annamaria Serturini",
"number": 15,
"position": null,
"position_code": null,
"rating": null
}
]
},
{
"team_name": "Lyon W",
"formation": "4-3-3",
"coach_name": "Jonatan Giráldez",
"starting_xi": [
{
"player_name": "Maria Grohs",
"number": 25,
"position": null,
"position_code": 11,
"rating": 7.1
},
{
"player_name": "Jule Brand",
"number": 29,
"position": null,
"position_code": 32,
"rating": 8.5
},
{
"player_name": "Wassa Sangaré",
"number": 26,
"position": null,
"position_code": 34,
"rating": 8
},
{
"player_name": "Wendie Renard",
"number": 3,
"position": null,
"position_code": 36,
"rating": 8.1
},
{
"player_name": "Selma Bacha",
"number": 4,
"position": null,
"position_code": 38,
"rating": 8.1
},
{
"player_name": "Lily Isabella Yohannes",
"number": 20,
"position": null,
"position_code": 73,
"rating": 8.6
},
{
"player_name": "Damaris Egurrola",
"number": 13,
"position": null,
"position_code": 75,
"rating": 7.6
},
{
"player_name": "Melchie Dumornay",
"number": 6,
"position": null,
"position_code": 77,
"rating": 8.7
},
{
"player_name": "Vicki Becho",
"number": 7,
"position": null,
"position_code": 103,
"rating": 7.5
},
{
"player_name": "Marie-Antoinette Katoto",
"number": 9,
"position": null,
"position_code": 105,
"rating": 9
},
{
"player_name": "Tabitha Chawinga",
"number": 11,
"position": null,
"position_code": 107,
"rating": 7.8
}
],
"substitutes": [
{
"player_name": "Salma Paralluelo",
"number": 77,
"position": null,
"position_code": null,
"rating": 7
},
{
"player_name": "Korbin Shrader",
"number": 8,
"position": null,
"position_code": null,
"rating": 7.7
},
{
"player_name": "Ada Stolsmo Hegerberg",
"number": 14,
"position": null,
"position_code": null,
"rating": 6
},
{
"player_name": "Tarciane",
"number": 33,
"position": null,
"position_code": null,
"rating": 6.3
},
{
"player_name": "Inès Benyahia",
"number": 10,
"position": null,
"position_code": null,
"rating": 6.2
},
{
"player_name": "Christiane Endler",
"number": 1,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Ashley Lawrence",
"number": 12,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Elma Junttila Nelhage",
"number": 5,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Ingrid Syrstad Engen",
"number": 15,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Maïssa Fathallah",
"number": 17,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Julie Swierot",
"number": 24,
"position": null,
"position_code": null,
"rating": null
},
{
"player_name": "Liana Joseph",
"number": 31,
"position": null,
"position_code": null,
"rating": null
}
]
}
],
"substitutions": [
{
"team_name": "Juventus W",
"minute": "46",
"player_off": "Eva Schatzer",
"player_on": "Júlia Bartel"
},
{
"team_name": "Juventus W",
"minute": "46",
"player_off": "Matilde Pavan",
"player_on": "Remina Chiba"
},
{
"team_name": "Juventus W",
"minute": "58",
"player_off": "Alba Redondo",
"player_on": "Amaiur Sarriegi"
},
{
"team_name": "Lyon W",
"minute": "60",
"player_off": "Tabitha Chawinga",
"player_on": "Salma Paralluelo"
},
{
"team_name": "Lyon W",
"minute": "65",
"player_off": "Marie-Antoinette Katoto",
"player_on": "Ada Stolsmo Hegerberg"
},
{
"team_name": "Lyon W",
"minute": "65",
"player_off": "Vicki Becho",
"player_on": "Korbin Shrader"
},
{
"team_name": "Juventus W",
"minute": "70",
"player_off": "Estela Carbonell",
"player_on": "Ornella Graziani"
},
{
"team_name": "Lyon W",
"minute": "75",
"player_off": "Damaris Egurrola",
"player_on": "Inès Benyahia"
},
{
"team_name": "Lyon W",
"minute": "75",
"player_off": "Wassa Sangaré",
"player_on": "Tarciane"
},
{
"team_name": "Juventus W",
"minute": "81",
"player_off": "Tatiana Pinto",
"player_on": "Cristina Librán"
}
],
"appearances": [
{
"team_name": "Juventus W",
"player_name": "Daniëlle de Jong",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Juventus W",
"player_name": "Kysha Sylla",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Juventus W",
"player_name": "Cecilia Salvai",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Juventus W",
"player_name": "Martina Lenzini",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Juventus W",
"player_name": "Tatiana Pinto",
"started": true,
"minute_on": 0,
"minute_off": 81,
"minutes_played": 81
},
{
"team_name": "Juventus W",
"player_name": "Manaka Hayashi",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Juventus W",
"player_name": "Eva Schatzer",
"started": true,
"minute_on": 0,
"minute_off": 46,
"minutes_played": 46
},
{
"team_name": "Juventus W",
"player_name": "Estela Carbonell",
"started": true,
"minute_on": 0,
"minute_off": 70,
"minutes_played": 70
},
{
"team_name": "Juventus W",
"player_name": "Danique Noordman",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Juventus W",
"player_name": "Alba Redondo",
"started": true,
"minute_on": 0,
"minute_off": 58,
"minutes_played": 58
},
{
"team_name": "Juventus W",
"player_name": "Matilde Pavan",
"started": true,
"minute_on": 0,
"minute_off": 46,
"minutes_played": 46
},
{
"team_name": "Lyon W",
"player_name": "Maria Grohs",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Lyon W",
"player_name": "Jule Brand",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Lyon W",
"player_name": "Wassa Sangaré",
"started": true,
"minute_on": 0,
"minute_off": 75,
"minutes_played": 75
},
{
"team_name": "Lyon W",
"player_name": "Wendie Renard",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Lyon W",
"player_name": "Selma Bacha",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Lyon W",
"player_name": "Lily Isabella Yohannes",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Lyon W",
"player_name": "Damaris Egurrola",
"started": true,
"minute_on": 0,
"minute_off": 75,
"minutes_played": 75
},
{
"team_name": "Lyon W",
"player_name": "Melchie Dumornay",
"started": true,
"minute_on": 0,
"minute_off": null,
"minutes_played": 90
},
{
"team_name": "Lyon W",
"player_name": "Vicki Becho",
"started": true,
"minute_on": 0,
"minute_off": 65,
"minutes_played": 65
},
{
"team_name": "Lyon W",
"player_name": "Marie-Antoinette Katoto",
"started": true,
"minute_on": 0,
"minute_off": 65,
"minutes_played": 65
},
{
"team_name": "Lyon W",
"player_name": "Tabitha Chawinga",
"started": true,
"minute_on": 0,
"minute_off": 60,
"minutes_played": 60
},
{
"team_name": "Juventus W",
"player_name": "Júlia Bartel",
"started": false,
"minute_on": 46,
"minute_off": null,
"minutes_played": 44
},
{
"team_name": "Juventus W",
"player_name": "Remina Chiba",
"started": false,
"minute_on": 46,
"minute_off": null,
"minutes_played": 44
},
{
"team_name": "Juventus W",
"player_name": "Amaiur Sarriegi",
"started": false,
"minute_on": 58,
"minute_off": null,
"minutes_played": 32
},
{
"team_name": "Lyon W",
"player_name": "Salma Paralluelo",
"started": false,
"minute_on": 60,
"minute_off": null,
"minutes_played": 30
},
{
"team_name": "Lyon W",
"player_name": "Ada Stolsmo Hegerberg",
"started": false,
"minute_on": 65,
"minute_off": null,
"minutes_played": 25
},
{
"team_name": "Lyon W",
"player_name": "Korbin Shrader",
"started": false,
"minute_on": 65,
"minute_off": null,
"minutes_played": 25
},
{
"team_name": "Juventus W",
"player_name": "Ornella Graziani",
"started": false,
"minute_on": 70,
"minute_off": null,
"minutes_played": 20
},
{
"team_name": "Lyon W",
"player_name": "Inès Benyahia",
"started": false,
"minute_on": 75,
"minute_off": null,
"minutes_played": 15
},
{
"team_name": "Lyon W",
"player_name": "Tarciane",
"started": false,
"minute_on": 75,
"minute_off": null,
"minutes_played": 15
},
{
"team_name": "Juventus W",
"player_name": "Cristina Librán",
"started": false,
"minute_on": 81,
"minute_off": null,
"minutes_played": 9
}
]
},
"meta": {
"data_as_of": "2026-11-12T06:18:54Z",
"request_id": "01J9QW3C7M4KX2VB",
"note": "Formation, starting eleven with shirt numbers and grid positions, substitutes and the coach for each side; every substitution with its minute; and each player who took part, with the minutes worked out from the substitutions."
}
}
Run it live
Paste your key and fire the real request. The key is kept in this browser only and never sent anywhere but the API.