GET/api/v1/matches/lineup/players

Get a match's lineups

Realtime data packageWorld Cup packageactivebetacoreAvailable (scoped)

Description

Returns the lineups of one match (use the "has lineups" field of the fixtures and results endpoint to decide whether to call this)
Request rate: 120/min

Coordinates:
Home team origin: top left; the x axis points right, the y axis points down;
Away team origin: bottom right; the x axis points left, the y axis points up.

Includes player events; limit: matches of the previous 30 days

PS: get the ids of changed matches from the 'data updates' endpoint

Access

Request: GET https://api.sports.csap.ai/api/v1/matches/lineup/players
Auth: Header X-API-Key: <your key> (Authorization: Bearer <key> also works; ?key= is still accepted but discouraged, because the key ends up in URLs and logs)
External keys: Available (scoped)External keys can call it, but only data inside the open scope is returned.
Rate limits: 3000 per minute · 200000 per day · Set per key (rate_per_min and quota_daily returned by /api/v1/account are authoritative; the numbers above are a trial key's). Beyond them the answer is 429. In addition, heavy requests such as whole-table snapshots and statistics lists without a match id are processed 2 at a time for the whole platform; a request that cannot get a slot receives 429 with Retry-After. Responses do not carry X-RateLimit-* headers for now. See the general guide

Request parameters 1

Parameter	Type	required	Example	Description
id	integer	required	`5179`	Match id

Example request

curl "https://api.sports.csap.ai/api/v1/matches/lineup/players?id=5179" \
  -H "X-API-Key: YOUR_API_KEY"

Try it

Example response

Real response with an external key at 09/11/2026, 14:28 UTC: HTTP 200, 1000 rows, 473 ms (data cut to 2 rows)

{
  "code": 0,
  "data": [
    {
      "away": null,
      "away_coach_id": null,
      "away_color": null,
      "away_formation": null,
      "away_score": null,
      "belong": "home",
      "captain": null,
      "confirmed": false,
      "first": null,
      "gpid": 109,
      "home": null,
      "home_coach_id": null,
      "home_color": null,
      "home_formation": null,
      "home_score": null,
      "id": 5390,
      "incidents": null,
      "is_substitute": false,
      "logo": null,
      "match_source": "S4",
      "name": "Phurba Tempa Lachenpa",
      "name_zh": "拉琴帕",
      "national_logo": null,
      "player": null,
      "player_id": "1207576",
      "player_name": "Phurba Lachenpa",
      "player_zh": null,
      "position": "11",
      "rating": null,
      "reason_type": null,
      "shirt_number": "1",
      "side": "home",
      "team_id": null,
      "time": null,
      "type": null,
      "updated_at": 1794081150598,
      "x": null,
      "y": null
    },
    {
      "away": null,
      "away_coach_id": null,
      "away_color": null,
      "away_formation": null,
      "away_score": null,
      "belong": "home",
      "captain": null,
      "confirmed": false,
      "first": null,
      "gpid": 111,
      "home": null,
      "home_coach_id": null,
      "home_color": null,
      "home_formation": null,
      "home_score": null,
      "id": 5391,
      "incidents": null,
      "is_substitute": false,
      "logo": null,
      "match_source": "S4",
      "name": "Diego Živulić",
      "name_zh": "祖维利奇",
      "national_logo": null,
      "player": null,
      "player_id": "251254",
      "player_name": "Diego Živulić",
      "player_zh": null,
      "position": "35",
      "rating": null,
      "reason_type": null,
      "shirt_number": "21",
      "side": "home",
      "team_id": null,
      "time": null,
      "type": null,
      "updated_at": 1794081150600,
      "x": null,
      "y": null
    }
  ],
  "message": "success",
  "success": true
}

Response fields 40

awaynullnullableAway team lineup players

away_coach_idnullnullableAway team's coach

away_colornullnullableAway team shirt colour

away_formationnullnullableAway team formation

away_scorenullnullableAway team score (regular time, including stoppage time)

belongstringSide: 0 neutral, 1 home, 2 awayExample: "home"

captainnullnullableCaptain: 1 yes, 0 no

confirmedbooleanWhether the lineup is confirmedExample: false

firstnullnullableStarter: 1 yes, 0 no

gpidintegerPlatform player idExample: 109

homenullnullableHome team lineup players

home_coach_idnullnullableHome team's coach

home_colornullnullableHome team shirt colour

home_formationnullnullableHome team formation

home_scorenullnullableHome team score (regular time, including stoppage time)

idintegerRecord id; paging cursor (the id parameter returns records >= this value). In match endpoints it is the platform match id (gmid)Example: 5390

incidentsnullnullablePlayer events; present when the player has events, absent by default

is_substitutebooleannullableWhether a substituteExample: false

logonullnullableLogo (image address on this platform; empty when there is none)

match_sourcestringSource code of this rowExample: "S4"

gmidintegernullablePlatform match id (gmid, unique across the platform)

namestringNameExample: "Phurba Tempa Lachenpa"

name_enstringEnglish nameExample: "Phurba Tempa Lachenpa"

name_zhstringnullableChinese nameExample: "拉琴帕"

national_logonullnullablePlayer logo (national team)

playernullnullablePlayer name

player_idstringPlayer idExample: "1207576"

player_namestringPlayer nameExample: "Phurba Lachenpa"

player_zhnullnullablePlayer's Chinese name

positionstringnullablePositionExample: "11"

ratingnullnullableRating

reason_typenullnullableReason for a card or substitution, see status codes -> event reasons (present for card and substitution events)

shirt_numberstringShirt numberExample: "1"

sidestringhome = home team / away = away teamExample: "home"

team_idnullnullableTeam id

timenullnullableTime / minute

typenullnullableType

updated_atintegerLast update time (UTC, ISO 8601; incremental sync with the time parameter goes by it)Example: 1794081150598

xnullnullableLineup x coordinate, out of 100

ynullnullableLineup y coordinate, out of 100

Errors

HTTP	message	When
401	`missing API key / unauthorized`	No X-API-Key, or the key is invalid or disabled
400	`bad param …`	Malformed parameter (e.g. id is neither a number nor u<uid>)
301	`match merged into <gmid>`	Queried by an old match id that has been merged into a new gmid: Location points to the new address and the body carries moved_to
404	`not found`	The match / team / competition does not exist, or is outside what this key can see (external keys see only matches inside the open coverage)
429	`rate limit exceeded / daily quota exceeded`	The key's per-minute rate or daily quota is exceeded
429	`server busy, retry later`	The server's concurrency slots are full (only 2 heavy requests at a time); retry after Retry-After seconds
500	`query error`	The query failed on the server; you may retry