Docs menu

ESPN API endpoint

ESPN team roster API

Returns a team's roster (players with position, jersey, age, and experience) plus head coach. The `sport` enum accepts `football`, `basketball`, `baseball`, `hockey`, and `soccer`. The `league` enum accepts `nfl`, `college-football`, `nba`, `wnba`, `mens-college-basketball`, `womens-college-basketball`, `mlb`, `nhl`, `eng.1`, `esp.1`, `ita.1`, `ger.1`, `fra.1`, `usa.1`, and `uefa.champions`; it must be valid for the chosen sport.

GETapiKey2 credits/requestESPNespn.rosterResponseDoc/espn/team-roster

Endpoint facts

Method: GET
API path: /espn/team-roster
Auth: apiKey
Credits: 2 credits/request
Charged on: Successful 2xx responses only
Platform: ESPN
Response schema: #/definitions/espn.rosterResponseDoc

ESPN API Try ESPN team roster API in Playground ESPN API documentation

How this endpoint behaves

Query parameters:

sport: required enum. Allowed values: football, basketball, baseball, hockey, soccer.
league: required enum, must be valid for the chosen sport. Allowed values: nfl, college-football, nba, wnba, mens-college-basketball, womens-college-basketball, mlb, nhl, eng.1, esp.1, ita.1, ger.1, fra.1, usa.1, uefa.champions.
team: required. Team id (numeric) or abbreviation, e.g. 12 or KC.

Notable response behavior:

Flat player lists and position-grouped lists both flatten to athletes.
An empty roster is treated as an upstream error (parser drift or block).
Invalid sport/league/team values return an invalid-parameter error before upstream IO.

Live monitoring

Monitored request: GET /espn/team-roster?league=nfl&sport=football&team=KC
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 1.07 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /espn/team-roster?league=nfl&sport=football&team=KC
Items in athletes: 76
Fields filled in every checked item: 6
Fields empty in some or all items: 2

Field	Filled in, of 76 checked	Values in the sample
id	76
full_name	76
jersey	73	1 to 99, median 44
position	76	“WR” and 15 other values
age	76	21 to 37, median 25
display_height	76
display_weight	76	“180 lbs” and 51 other values
experience_years	56	1 to 14, median 4

Request parameters

Parameter	Type	Required	Description	Example
sport	string	Yes	Sport key Allowed values: football, basketball, baseball, hockey, soccer.	football
league	string	Yes	League key (must be valid for the sport) Allowed values: nfl, college-football, nba, wnba, mens-college-basketball, womens-college-basketball, mlb, nhl, eng.1, esp.1, ita.1, ger.1, fra.1, usa.1, uefa.champions.	nfl
team	string	Yes	Team id (numeric) or abbreviation	KC
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/espn/team-roster?sport=football&league=nfl&team=KC" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "sport": "football",
    "league": "nfl",
    "team": {
      "id": "12",
      "abbreviation": "KC",
      "display_name": "Kansas City Chiefs"
    },
    "coach": "Andy Reid",
    "count": 1,
    "source_url": "https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/KC/roster",
    "fetched_at": "2026-07-06T00:00:00Z",
    "athletes": [
      {
        "id": "3139477",
        "full_name": "Patrick Mahomes",
        "jersey": "15",
        "position": "QB",
        "age": 30,
        "display_height": "6' 3\"",
        "experience_years": 9
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/espn.rosterResponseDoc

Field	Type	Required	Example	Description
code	integer	No	200
data	espn.RosterResponse	No
data.athletes	array	No		Players on the team roster, one entry per player.
data.athletes[].age	integer	No		Player's age in years.
data.athletes[].display_height	string	No		Player's height as ESPN displays it.
data.athletes[].display_weight	string	No		Player's weight as ESPN displays it.
data.athletes[].experience_years	integer	No		Number of years of experience the player has.
data.athletes[].full_name	string	No		Player's full name.
data.athletes[].id	string	No		ESPN athlete id of the player.
data.athletes[].jersey	string	No		Player's jersey number, as a string.
data.athletes[].position	string	No		Player's position on the team.
data.coach	string	No		Name of the team's head coach. Omitted when ESPN lists none.
data.count	integer	No		Number of athletes returned.
data.fetched_at	string	No		Time the data was fetched, in UTC (RFC 3339).
data.league	string	No		League key that was requested, for example `nfl`.
data.source_url	string	No		URL the data was read from.
data.sport	string	No		Sport key that was requested, for example `football`.
data.team	object	No		Team the roster belongs to.
data.team.abbreviation	string	No	KC	Short team code, for example `KC`.
data.team.alternate_color	string	No		Team's secondary colour code, as ESPN gives it.
data.team.color	string	No		Team's primary colour code, as ESPN gives it.
data.team.display_name	string	No	Kansas City Chiefs	Full team name, for example `Kansas City Chiefs`.
data.team.id	string	No	12	ESPN team id, for example `12`. Use it as the `team` parameter of the team and roster endpoints.
data.team.location	string	No	Kansas City	Team's city or region, for example `Kansas City`.
data.team.logo	string	No		URL of the team logo image.
data.team.name	string	No	Chiefs	Team nickname without the location, for example `Chiefs`.
data.team.short_display_name	string	No	Chiefs	Shortened team name, for example `Chiefs`.
data.team.uid	string	No		ESPN's unique identifier string for the team.
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
404	Not Found	#/definitions/app.Response
429	Too Many Requests	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/espn/team-roster?sport=football&league=nfl&team=KC" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More ESPN endpoint docs ESPN API ESPN athlete API documentation ESPN game summary API documentation ESPN league news API documentation ESPN poll rankings API documentation ESPN scoreboard API documentation ESPN standings API documentation

Open in Playground Back to group

Docs menu

ESPN API endpoint

ESPN team roster API

GETapiKey2 credits/requestESPNespn.rosterResponseDoc/espn/team-roster

Endpoint facts

Method: GET
API path: /espn/team-roster
Auth: apiKey
Credits: 2 credits/request
Charged on: Successful 2xx responses only
Platform: ESPN
Response schema: #/definitions/espn.rosterResponseDoc

ESPN API Try ESPN team roster API in Playground ESPN API documentation

How this endpoint behaves

Query parameters:

sport: required enum. Allowed values: football, basketball, baseball, hockey, soccer.
league: required enum, must be valid for the chosen sport. Allowed values: nfl, college-football, nba, wnba, mens-college-basketball, womens-college-basketball, mlb, nhl, eng.1, esp.1, ita.1, ger.1, fra.1, usa.1, uefa.champions.
team: required. Team id (numeric) or abbreviation, e.g. 12 or KC.

Notable response behavior:

Flat player lists and position-grouped lists both flatten to athletes.
An empty roster is treated as an upstream error (parser drift or block).
Invalid sport/league/team values return an invalid-parameter error before upstream IO.

Live monitoring

Monitored request: GET /espn/team-roster?league=nfl&sport=football&team=KC
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 1.07 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /espn/team-roster?league=nfl&sport=football&team=KC
Items in athletes: 76
Fields filled in every checked item: 6
Fields empty in some or all items: 2

Field	Filled in, of 76 checked	Values in the sample
id	76
full_name	76
jersey	73	1 to 99, median 44
position	76	“WR” and 15 other values
age	76	21 to 37, median 25
display_height	76
display_weight	76	“180 lbs” and 51 other values
experience_years	56	1 to 14, median 4

Request parameters

Parameter	Type	Required	Description	Example
sport	string	Yes	Sport key Allowed values: football, basketball, baseball, hockey, soccer.	football
league	string	Yes	League key (must be valid for the sport) Allowed values: nfl, college-football, nba, wnba, mens-college-basketball, womens-college-basketball, mlb, nhl, eng.1, esp.1, ita.1, ger.1, fra.1, usa.1, uefa.champions.	nfl
team	string	Yes	Team id (numeric) or abbreviation	KC
x-api-key (header)	string	Yes	API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/espn/team-roster?sport=football&league=nfl&team=KC" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "sport": "football",
    "league": "nfl",
    "team": {
      "id": "12",
      "abbreviation": "KC",
      "display_name": "Kansas City Chiefs"
    },
    "coach": "Andy Reid",
    "count": 1,
    "source_url": "https://site.api.espn.com/apis/site/v2/sports/football/nfl/teams/KC/roster",
    "fetched_at": "2026-07-06T00:00:00Z",
    "athletes": [
      {
        "id": "3139477",
        "full_name": "Patrick Mahomes",
        "jersey": "15",
        "position": "QB",
        "age": 30,
        "display_height": "6' 3\"",
        "experience_years": 9
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/espn.rosterResponseDoc

Field	Type	Required	Example	Description
code	integer	No	200
data	espn.RosterResponse	No
data.athletes	array	No		Players on the team roster, one entry per player.
data.athletes[].age	integer	No		Player's age in years.
data.athletes[].display_height	string	No		Player's height as ESPN displays it.
data.athletes[].display_weight	string	No		Player's weight as ESPN displays it.
data.athletes[].experience_years	integer	No		Number of years of experience the player has.
data.athletes[].full_name	string	No		Player's full name.
data.athletes[].id	string	No		ESPN athlete id of the player.
data.athletes[].jersey	string	No		Player's jersey number, as a string.
data.athletes[].position	string	No		Player's position on the team.
data.coach	string	No		Name of the team's head coach. Omitted when ESPN lists none.
data.count	integer	No		Number of athletes returned.
data.fetched_at	string	No		Time the data was fetched, in UTC (RFC 3339).
data.league	string	No		League key that was requested, for example `nfl`.
data.source_url	string	No		URL the data was read from.
data.sport	string	No		Sport key that was requested, for example `football`.
data.team	object	No		Team the roster belongs to.
data.team.abbreviation	string	No	KC	Short team code, for example `KC`.
data.team.alternate_color	string	No		Team's secondary colour code, as ESPN gives it.
data.team.color	string	No		Team's primary colour code, as ESPN gives it.
data.team.display_name	string	No	Kansas City Chiefs	Full team name, for example `Kansas City Chiefs`.
data.team.id	string	No	12	ESPN team id, for example `12`. Use it as the `team` parameter of the team and roster endpoints.
data.team.location	string	No	Kansas City	Team's city or region, for example `Kansas City`.
data.team.logo	string	No		URL of the team logo image.
data.team.name	string	No	Chiefs	Team nickname without the location, for example `Chiefs`.
data.team.short_display_name	string	No	Chiefs	Shortened team name, for example `Chiefs`.
data.team.uid	string	No		ESPN's unique identifier string for the team.
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
404	Not Found	#/definitions/app.Response
429	Too Many Requests	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/espn/team-roster?sport=football&league=nfl&team=KC" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

Open in Playground Back to group

ESPN team roster API

Endpoint facts

How this endpoint behaves

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

ESPN team roster API

Endpoint facts

How this endpoint behaves

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related