Skip to content

Instantly share code, notes, and snippets.

@nntrn

nntrn/espn-api-list.md

Last active November 2, 2025 19:37
Show Gist options
  • Save nntrn/ee26cb2a0716de0947a0a4e9a157bc1c to your computer and use it in GitHub Desktop.
Save nntrn/ee26cb2a0716de0947a0a4e9a157bc1c to your computer and use it in GitHub Desktop.
Download ZIP
List of nfl api endpoints from espn
Raw
espn-api-list.md

List of NFL API Endpoints

This page has been updated a lot in the past 3 years. Older revisions you might like more than this one:

  • June 2021 - list of endpoints for other sports/leagues (i.e. nba, nhl, mlb)
  • August 2021 - get historical fantasy league data
  • September 2021 - list of endpoints in plain text
  • May 2023 - collapsed endpoint response examples
  • Mar 2025 - endpoints from partners.api.espn.com *NEW*

Additional Resources

Notes

  • This page is limited to NFL endpoints but can be refashioned for other leagues (i.e. /sports/football/leagues/nfl/ => /sports/baseball/leagues/mlb/)
    List of ESPN leagues: API | Document

    Games Today (for all sports)

Paramaters

  • {YEAR}: Football season (YYYY)
  • {SEASONTYPE}: 1=pre, 2=regular, 3=post, 4=off
  • {EVENT_ID}: game id
  • {TEAM_ID}: 1-32 (view all)
  • {ATHLETE_ID}: view all
  • {FANTASY_LEAGUE_ID}: Fantasy league id
  • {BET_PROVIDER_ID}: view all

Table of Contents

Reference List

Get list of ids

News

Detailed

Get live updates (xhr=1)

Teams

Games

Athletes

Calendar

Odds

Scoreboard

Leagues

Search

Pick em challenges

Parameters

  • {USER_GAME_ID}
  • {GROUP_ID}
  • {CHALLENGE_ID} and {CHALLENGE_NAME}
  • {VIEW_NAME}
    • ⭐ allon
    • ⭐ chui_default
    • chui_default_group
    • chui_default_groupParticipationHistory
    • chui_default_metadata
    • chui_pagetype_group_picks
    • pagetype_leaderboard

Fantasy

v3 header:
X-Fantasy-Filter: {"players":{"limit":2000},"filterActive":{"value":true}}

Curl Fantasy Filters

Fantasy Stats

  • Position

    { "1": "QB",
  "2": "RB",
  "3": "WR",
  "4": "TE",
  "5": "K",
 "16": "DST" }

  • Player stats
    View

Endpoints

Athlete endpoints

Calendar endpoints

Blacklist dates, whitelist dates, events

Season endpoints

Game weeks, Season types, weekly events, weekly picks

Betting endpoints

Betting, odds, draft

Metainfo endpoints

Franchise, news, venues

Team endpoints

Depthcharts, injuries, coaches, roster, odds records

Fantasy endpoints

Raw
new.md

Athletes:

https://partners.api.espn.com/v2/sports/football/nfl/athletes?limit=7000

https://sports.core.api.espn.com/v3/sports/football/nfl/athletes?page=1&limit=20000

Events

https://partners.api.espn.com/v2/sports/football/nfl/events?limit=1000
&dates=20230101-20240101 or &dates=20230101 or &dates=2023

Fantasy

https://lm-api-reads.fantasy.espn.com/apis/v3/games/ffl/seasons/{{YEAR}}/players?view={{VIEW_NAME}}

# To get more than 50 items, run in terminal:
curl -H 'X-Fantasy-Filter: {"games":{"limit":2000}}' <URL>

Views (that I know of):

Stat column names

id   displayid  abbrev    description
---  ---------  --------  --------------------------------
0    7          PA        Each Pass Attempted
1    8          PC        Each Pass Completed
2    11         INC       Each Incomplete Pass
3    0          PY        Passing Yards
4    14         PTD       TD Pass
5    1          PY5       Every 5 passing yards
6    2          PY10      Every 10 passing yards
View more 
id   displayid  abbrev    description
---  ---------  --------  --------------------------------
0    7          PA        Each Pass Attempted
1    8          PC        Each Pass Completed
2    11         INC       Each Incomplete Pass
3    0          PY        Passing Yards
4    14         PTD       TD Pass
5    1          PY5       Every 5 passing yards
6    2          PY10      Every 10 passing yards
7    3          PY20      Every 20 passing yards 
8    4          PY25      Every 25 passing yards 
9    5          PY50      Every 50 passing yards
10   6          PY100     Every 100 passing yards
11   9          PC5       Every 5 pass completions
12   10         PC10      Every 10 pass completions
13   12         IP5       Every 5 pass incompletions
14   13         IP10      Every 10 pass incompletions
15   15         PTD40     40+ yard TD pass bonus
16   16         PTD50     50+ yard TD pass bonus
17   20         P300      300-399 yard passing game
18   21         P400      400+ yard passing game
19   19         2PC       2pt Passing Conversion
20   18         INTT      Interceptions Thrown
21   155        CPCT      Passing Completion Pct
22   156        PYPG      Passing Yards Per Game
23   30         RA        Rushing Attempts
24   23         RY        Rushing Yards
25   33         RTD       TD Rush
26   37         2PR       2pt Rushing Conversion
27   24         RY5       Every 5 rushing yards
28   25         RY10      Every 10 rushing yards
29   26         RY20      Every 20 rushing yards
30   27         RY25      Every 25 rushing yards 
31   28         RY50      Every 50 rushing yards
32   29         R100      Every 100 rushing yards
33   31         RA5       Every 5 rush attempts
34   32         RA10      Every 10 rush attempts
35   34         RTD40     40+ yard TD rush bonus
36   35         RTD50     50+ yard TD rush bonus
37   38         RY100     100-199 yard rushing game
38   39         RY200     200+ yard rushing game
39   157        RYPA      Rushing Yards Per Attempt
40   158        RYPG      Rushing Yards Per Game
41   159        RECS      Receptions
42   40         REY       Receiving Yards
43   50         RETD      TD Reception
44   54         2PRE      2pt Receiving Conversion
45   51         RETD40    40+ yard TD rec bonus
46   52         RETD50    50+ yard TD rec bonus
47   41         REY5      Every 5 receiving yards
48   42         REY10     Every 10 receiving yards
49   43         REY20     Every 20 receiving yards
50   44         REY25     Every 25 receiving yards
51   45         REY50     Every 50 receiving yards
52   46         RE100     Every 100 receiving yards
53   47         REC       Each reception
54   48         REC5      Every 5 receptions
55   49         REC10     Every 10 receptions
56   55         REY100    100-199 yard receiving game
57   56         REY200    200+ yard receiving game
58   57         RET       Receiving Target
59   160        YAC       Receiving Yards After Catch
60   161        YPC       Receiving Yards Per Catch
61   162        REYPG     Receiving Yards Per Game
62   163        PTL       Total 2pt Conversions
63   66         FTD       Fumble Recovered for TD
64   22         SKD       Sacked
65   164        PFUM      Passing Fumbles
66   165        RFUM      Rushing Fumbles
67   166        REFUM     Receiving Fumbles
68   67         FUM       Total Fumbles
69   167        PFUML     Passing Fumbles Lost
70   168        RFUML     Rushing Fumbles Lost
71   169        REFUML    Receiving Fumbles Lost
72   68         FUML      Total Fumbles Lost
73   170        TT        Total Turnovers
74   84         FG50P     FG Made (50+ yards)
75   171        FGA50P    FG Attempted (50+ yards)
76   172        FGM50P    FG Missed (50+ yards)
77   83         FG40      FG Made (40-49 yards)
78   86         FGA40     FG Attempted (40-49 yards)
79   89         FGM40     FG Missed (40-49 yards)
80   82         FG0       FG Made (0-39 yards)
81   85         FGA0      FG Attempted (0-39 yards)
82   88         FGM0      FG Missed (0-39 yards)
83   79         FG        Total FG Made
84   80         FGA       Total FG Attempted
85   81         FGM       Total FG Missed
86   76         PAT       Each PAT Made
87   77         PATA      Each PAT Attempted
88   78         PATM      Each PAT Missed
89   136        PA0       0 points allowed
90   137        PA1       1-6 points allowed
91   138        PA7       7-13 points allowed
92   139        PA14      14-17 points allowed
93   73         BLKKRTD   Blocked Punt or FG return for TD
94   173        DEFRETTD  Fumble or INT Return for TD
95   113        INT       Each Interception
96   114        FR        Each Fumble Recovered
97   112        BLKK      Blocked Punt, PAT or FG
98   116        SF        Each Safety
99   107        SK        Each Sack
100  108        HALFSK    1/2 Sack
101  64         KRTD      Kickoff Return TD
102  65         PRTD      Punt Return TD
103  71         INTTD     Interception Return TD
104  72         FRTD      Fumble Return TD
105  174        TRTD      Total Return TD
106  115        FF        Each Fumble Forced
107  117        TKA       Assisted Tackles
108  118        TKS       Solo Tackles
109  109        TK        Total Tackles
110  110        TK3       Every 3 Total Tackles
111  111        TK5       Every 5 Total Tackles
112  119        STF       Stuffs
113  120        PD        Passes Defensed
114  58         KR        Kickoff Return Yards
115  61         PR        Punt Return Yards
116  59         KR10      Every 10 kickoff return yards
117  60         KR25      Every 25 kickoff return yards
118  62         PR10      Every 10 punt return yards
119  63         PR25      Every 25 punt return yards
120  135        PTSA      Points Allowed
121  140        PA18      18-21 points allowed
122  141        PA22      22-27 points allowed
123  142        PA28      28-34 points allowed
124  143        PA35      35-45 points allowed
125  144        PA46      46+ points allowed
126  175        PAPG      Points Allowed Per Game
127  145        YA        Yards Allowed
128  146        YA100     Less than 100 total yards allowed
129  147        YA199     100-199 total yards allowed
130  148        YA299     200-299 total yards allowed
131  149        YA349     300-349 total yards allowed
132  150        YA399     350-399 total yards allowed
133  151        YA449     400-449 total yards allowed
134  152        YA499     450-499 total yards allowed
135  153        YA549     500-549 total yards allowed
136  154        YA550     550+ total yards allowed
137  176        YAPG      Yards Allowed Per Game
138  91         PT        Net Punts
139  92         PTY       Punt Yards
140  93         PT10      Punts Inside the 10
141  94         PT20      Punts Inside the 20
142  95         PTB       Blocked Punts
143  96         PTR       Punts Returned
144  97         PTRY      Punt Return Yards
145  98         PTTB      Touchbacks
146  99         PTFC      Fair Catches
147  177        PTAVG     Punt Average
148  100        PTA44     Punt Average 44.0+
149  101        PTA42     Punt Average 42.0-43.9
150  102        PTA40     Punt Average 40.0-41.9
151  103        PTA38     Punt Average 38.0-39.9
152  104        PTA36     Punt Average 36.0-37.9
153  105        PTA34     Punt Average 34.0-35.9
154  106        PTA33     Punt Average 33.9 or less
155  69         TW        Team Win
156  70         TL        Team Loss
157  121        TIE       Team Tie
158  122        PTS       Points Scored
159  178        PPG       Points Scored Per Game
160  179        MGN       Margin of Victory
161  123        WM25      25+ point Win Margin
162  124        WM20      20-24 point Win Margin
163  125        WM15      15-19 point Win Margin
164  126        WM10      10-14 point Win Margin
165  127        WM5       5-9 point Win Margin
166  128        WM1       1-4 point Win Margin
167  129        LM1       1-4 point Loss Margin
168  130        LM5       5-9 point Loss Margin
169  131        LM10      10-14 point Loss Margin
170  132        LM15      15-19 point Loss Margin
171  133        LM20      20-24 point Loss Margin
172  134        LM25      25+ point Loss Margin
173  180        MGNPG     Margin of Victory Per Game
174  181        WINPCT    Winning Pct
175  182        PTD0      0-9 yd TD pass bonus
176  183        PTD10     10-19 yd TD pass bonus
177  184        PTD20     20-29 yd TD pass bonus
178  185        PTD30     30-39 yd TD pass bonus
179  186        RTD0      0-9 yd TD rush bonus
180  187        RTD10     10-19 yd TD rush bonus
181  188        RTD20     20-29 yd TD rush bonus
182  189        RTD30     30-39 yd TD rush bonus
183  190        RETD0     0-9 yd TD rec bonus
184  191        RETD10    10-19 yd TD rec bonus
185  192        RETD20    20-29 yd TD rec bonus
186  193        RETD30    30-39 yd TD rec bonus
187  194        DPTSA     D/ST Points Allowed
188  195        DPA0      D/ST 0 points allowed
189  196        DPA1      D/ST 1-6 points allowed
190  197        DPA7      D/ST 7-13 points allowed
191  198        DPA14     D/ST 14-17 points allowed
192  199        DPA18     D/ST 18-21 points allowed
193  200        DPA22     D/ST 22-27 points allowed
194  201        DPA28     D/ST 28-34 points allowed
195  202        DPA35     D/ST 35-45 points allowed
196  203        DPA46     D/ST 46+ points allowed
197  204        DPAPG     D/ST Points Allowed Per Game
198  205        FG50      FG Made (50-59 yards)
199  87         FGA50     FG Attempted (50-59 yards)
200  90         FGM50     FG Missed (50-59 yards)
201  206        FG60      FG Made (60+ yards)
202  207        FGA60     FG Attempted (60+ yards)
203  208        FGM60     FG Missed (60+ yards)
204  209        O2PRET    Offensive 2pt Return
205  210        D2PRET    Defensive 2pt Return
206  74         2PRET     2pt Return
207  211        O1PSF     Offensive 1pt Safety
208  212        D1PSF     Defensive 1pt Safety
209  75         1PSF      1pt Safety
210  213        GP        Games Played
211  17         PFD       Passing First Down
212  36         RFD       Rushing First Down
213  53         REFD      Receiving First Down
214  214        FGY       FG Made Yards
215  215        FGMY      FG Missed Yards
216  216        FGAY      FG Attempt Yards
217  217        FGY5      Every 5 FG Made yards
218  218        FGY10     Every 10 FG Made yards
219  219        FGY20     Every 20 FG Made yards
220  220        FGY25     Every 25 FG Made yards
221  221        FGY50     Every 50 FG Made yards
222  222        FGY100    Every 100 FG Made yards
223  223        FGMY5     Every 5 FG Missed yards
224  224        FGMY10    Every 10 FG Missed yards
225  225        FGMY20    Every 20 FG Missed yards
226  226        FGMY25    Every 25 FG Missed yards
227  227        FGMY50    Every 50 FG Missed yards
228  228        FGMY100   Every 100 FG Missed yards
229  229        FGAY5     Every 5 FG Attempt yards
230  230        FGAY10    Every 10 FG Attempt yards
231  231        FGAY20    Every 20 FG Attempt yards
232  232        FGAY25    Every 25 FG Attempt yards
233  233        FGAY50    Every 50 FG Attempt yards
234  234        FGAY100   Every 100 FG Attempt yards
@nntrn
Copy link
Author

nntrn commented Jul 27, 2025

I see that I could potentially make a call to each player endpoint or to each game endpoint, but I'm guessing that I could add headers to one of these requests to just get the stats for the games happening today for only a certain set of playerIds. Does any endpoint come to mind?

@macsochor, if you want players playing THAT day, check out the xhr links

@guizucolotto
Copy link

I think I missed something, what call do I get the information from the Stats example at the end of this .md?

@JimNayzium
Copy link

JimNayzium commented Jul 28, 2025 •
edited by nntrn
Loading

I have a fun one that is quite maddening. (No pun intended)
In the drive play-by-play feed from a Bills game week 1 with id: 401671617
There was a discrepancy in the totals I was getting for James Cook's stats and I found a mistake by ESPN apparently.
I see no real way to know the mistake should be discounted or removed in the feeds either, at least not in these feeds. Other than comparing the stat totals at the end, but then determining what is wrong is near impossible.

I compared the PDF at nfl.com of the play by play hard copy of the actual game on these two plays and it would seem that the James Cook 11 yard rush does not exist at all. Somehow it just got entered for James Cook. Typically if a penalty happens or a play is reviewed that is well documented by ESPN's feeds. This is a pure mistake I am afraid. Like the intern who entered the data just shanked.

To be clear, this first play just doesn't appear in the https://static.www.nfl.com/gamecenter/7d40236a-1312-11ef-afd1-646009f18b2e.pdf report here. And if you look at the json data you will see the same exact clock times.

I guess this is the type thing that causes a "stat" correction to be made in fantasy maybe?

Any thoughts on a way to detect these type things? Something I am missing?

{
			"id": "4016716173400",
			"end": {
				"down": 1,
				"team": {
					"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/teams/2?lang=en&amp;region=us"
				},
				"distance": 13,
				"yardLine": 43,
				"possessionText": "BUF 43",
				"yardsToEndzone": 57,
				"downDistanceText": "1st &amp; 13 at BUF 43",
				"shortDownDistanceText": "1st &amp; 13"
			},
			"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/plays/4016716173400?lang=en&amp;region=us",
			"team": {
				"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/teams/2?lang=en&amp;region=us"
			},
			"text": "(Shotgun) J.Cook to BUF 43 for 11 yards.",
			"type": {
				"id": "5",
				"text": "Rush",
				"abbreviation": "RUSH"
			},
			"clock": {
				"value": 449,
				"displayValue": "7:29"
			},
			"drive": {
				"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/drives/40167161716?lang=en&amp;region=us"
			},
			"start": {
				"down": 2,
				"team": {
					"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/teams/2?lang=en&amp;region=us"
				},
				"distance": 8,
				"yardLine": 32,
				"possessionText": "BUF 32",
				"yardsToEndzone": 68,
				"downDistanceText": "2nd &amp; 8 at BUF 32",
				"shortDownDistanceText": "2nd &amp; 8"
			},
			"period": {
				"number": 4
			},
			"modified": "2024-09-11T20:51Z",
			"priority": false,
			"awayScore": 28,
			"homeScore": 31,
			"shortText": "James Cook 11 Yd Rush",
			"wallclock": "2024-09-08T19:40:06Z",
			"scoreValue": 0,
			"probability": {
				"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/probabilities/4016716173400?lang=en&amp;region=us"
			},
			"scoringPlay": false,
			"statYardage": 11,
			"participants": [
				{
					"type": "rusher",
					"order": 1,
					"stats": [
						{
							"name": "rushingAttempts",
							"value": 19,
							"description": "The total number of attempted rushes.",
							"displayName": "Rushing Attempts",
							"abbreviation": "ATT",
							"displayValue": "19",
							"shortDisplayName": "Rushing Attempts"
						},
						{
							"name": "rushingYards",
							"value": 71,
							"description": "The total rushing yards.",
							"displayName": "Rushing Yards",
							"abbreviation": "YDS",
							"displayValue": "71",
							"shortDisplayName": "Rush Yards"
						},
						{
							"name": "rushingTouchdowns",
							"value": 0,
							"description": "The total number of rushing touchdowns.",
							"displayName": "Rushing Touchdowns",
							"abbreviation": "TD",
							"displayValue": "0",
							"shortDisplayName": "Rushing Touchdowns"
						}
					],
					"athlete": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/athletes/4379399?lang=en&amp;region=us"
					},
					"position": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/positions/9?lang=en&amp;region=us"
					},
					"statistics": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/competitors/2/roster/4379399/statistics/0?lang=en&amp;region=us"
					}
				}
			],
			"sequenceNumber": "340000",
			"alternativeText": "(Shotgun) J.Cook to BUF 43 for 11 yards.",
			"yardsAfterCatch": 0,
			"shortAlternativeText": "James Cook 11 Yd Rush"
		},
		{
			"id": "4016716173426",
			"end": {
				"down": 2,
				"team": {
					"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/teams/2?lang=en&amp;region=us"
				},
				"distance": 11,
				"yardLine": 43,
				"possessionText": "BUF 43",
				"yardsToEndzone": 57,
				"downDistanceText": "2nd &amp; 11 at BUF 43",
				"shortDownDistanceText": "2nd &amp; 11"
			},
			"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/plays/4016716173426?lang=en&amp;region=us",
			"team": {
				"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/teams/2?lang=en&amp;region=us"
			},
			"text": "J.Allen pass short left to D.Kincaid to BUF 43 for 11 yards (S.Murphy-Bunting, O.Pappoe).",
			"type": {
				"id": "24",
				"text": "Pass Reception",
				"abbreviation": "REC"
			},
			"clock": {
				"value": 449,
				"displayValue": "7:29"
			},
			"drive": {
				"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/drives/40167161716?lang=en&amp;region=us"
			},
			"start": {
				"down": 2,
				"team": {
					"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/teams/2?lang=en&amp;region=us"
				},
				"distance": 8,
				"yardLine": 32,
				"possessionText": "BUF 32",
				"yardsToEndzone": 68,
				"downDistanceText": "2nd &amp; 8 at BUF 32",
				"shortDownDistanceText": "2nd &amp; 8"
			},
			"period": {
				"number": 4
			},
			"modified": "2024-09-11T20:51Z",
			"priority": false,
			"awayScore": 28,
			"homeScore": 31,
			"shortText": "Josh Allen Pass Complete for 11 Yds to Dalton Kincaid",
			"wallclock": "2024-09-08T19:39:58Z",
			"scoreValue": 0,
			"probability": {
				"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/probabilities/4016716173426?lang=en&amp;region=us"
			},
			"scoringPlay": false,
			"statYardage": 11,
			"participants": [
				{
					"type": "passer",
					"order": 1,
					"stats": [
						{
							"name": "completions/attempts",
							"value": 0.7826086957,
							"description": "The number of passing completions and attempts.",
							"displayName": "Completions / Attempts",
							"abbreviation": "COMP/ATT",
							"displayValue": "18/23",
							"shortDisplayName": "COMP/ATT"
						},
						{
							"name": "passingYards",
							"value": 232,
							"description": "The total passing yards.",
							"displayName": "Passing Yards",
							"abbreviation": "YDS",
							"displayValue": "232",
							"shortDisplayName": "Pass Yards"
						},
						{
							"name": "passingTouchdowns",
							"value": 2,
							"description": "The total number of passing touchdowns.",
							"displayName": "Passing Touchdowns",
							"abbreviation": "TD",
							"displayValue": "2",
							"shortDisplayName": "Touchdowns"
						},
						{
							"name": "interceptions",
							"value": 0,
							"description": "The total number of interceptions.",
							"displayName": "Interceptions",
							"abbreviation": "INT",
							"displayValue": "0",
							"shortDisplayName": "Interceptions"
						}
					],
					"athlete": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/athletes/3918298?lang=en&amp;region=us"
					},
					"position": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/positions/8?lang=en&amp;region=us"
					},
					"statistics": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/competitors/2/roster/3918298/statistics/0?lang=en&amp;region=us"
					}
				},
				{
					"type": "receiver",
					"order": 2,
					"stats": [
						{
							"name": "receptions",
							"value": 1,
							"description": "The total number of receptions.",
							"displayName": "Receptions",
							"abbreviation": "REC",
							"displayValue": "1",
							"shortDisplayName": "Receptions"
						},
						{
							"name": "receivingYards",
							"value": 11,
							"description": "The total receiving yards.",
							"displayName": "Receiving Yards",
							"abbreviation": "YDS",
							"displayValue": "11",
							"shortDisplayName": "Rec. Yards"
						},
						{
							"name": "receivingTouchdowns",
							"value": 0,
							"description": "The total number of receiving touchdowns.",
							"displayName": "Receiving Touchdowns",
							"abbreviation": "TD",
							"displayValue": "0",
							"shortDisplayName": "Receiving Touchdowns"
						}
					],
					"athlete": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/athletes/4385690?lang=en&amp;region=us"
					},
					"position": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/positions/7?lang=en&amp;region=us"
					},
					"statistics": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/competitors/2/roster/4385690/statistics/0?lang=en&amp;region=us"
					}
				},
				{
					"type": "tackler",
					"order": 3,
					"stats": [
						{
							"name": "totalTackles",
							"value": 5,
							"description": "The total number of tackles.",
							"displayName": "Total Tackles",
							"abbreviation": "TOT",
							"displayValue": "5",
							"shortDisplayName": "Tackles"
						},
						{
							"name": "sacks",
							"value": 0,
							"description": "The total number of sacks.",
							"displayName": "Sacks",
							"abbreviation": "SACK",
							"displayValue": "0",
							"shortDisplayName": "Sacks"
						},
						{
							"name": "interceptions",
							"value": 0,
							"description": "The total number of interceptions.",
							"displayName": "Interceptions",
							"abbreviation": "INT",
							"displayValue": "0",
							"shortDisplayName": "Interceptions"
						}
					],
					"athlete": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/athletes/3932886?lang=en&amp;region=us"
					},
					"position": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/positions/29?lang=en&amp;region=us"
					},
					"statistics": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/competitors/22/roster/3932886/statistics/0?lang=en&amp;region=us"
					}
				},
				{
					"type": "assistedBy",
					"order": 4,
					"stats": [
						{
							"name": "totalTackles",
							"value": 4,
							"description": "The total number of tackles.",
							"displayName": "Total Tackles",
							"abbreviation": "TOT",
							"displayValue": "4",
							"shortDisplayName": "Tackles"
						},
						{
							"name": "sacks",
							"value": 0,
							"description": "The total number of sacks.",
							"displayName": "Sacks",
							"abbreviation": "SACK",
							"displayValue": "0",
							"shortDisplayName": "Sacks"
						},
						{
							"name": "interceptions",
							"value": 0,
							"description": "The total number of interceptions.",
							"displayName": "Interceptions",
							"abbreviation": "INT",
							"displayValue": "0",
							"shortDisplayName": "Interceptions"
						}
					],
					"athlete": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/seasons/2024/athletes/4567219?lang=en&amp;region=us"
					},
					"position": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/positions/30?lang=en&amp;region=us"
					},
					"statistics": {
						"$ref": "http://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671617/competitions/401671617/competitors/22/roster/4567219/statistics/0?lang=en&amp;region=us"
					}
				}
			],
			"sequenceNumber": "342600",
			"alternativeText": "J.Allen pass short left to D.Kincaid to BUF 43 for 11 yards (S.Murphy-Bunting, O.Pappoe).",
			"yardsAfterCatch": 0,
			"shortAlternativeText": "Josh Allen Pass Complete for 11 Yds to Dalton Kincaid"
		},

@KieranMunslow
Copy link

@JimNayzium, I've taken a look at what you've mentioned and think you're spot on with this being a phantom play.

In terms of detecting things like this, it seems pretty tough as the non-existent play is populated as though its real. The one discrepancy I can find is the value of the wallclock field. I've listed a few plays around the play you're looking and the fake Cook play breaks the sequence. Its hard to know if this will be the case in other instances though.

The real Cook rush with penalty on play - 2024-09-08T19:39:07Z
The phantom Cook rush - 2024-09-08T19:40:06Z
The Kincaid pass - 2024-09-08T19:39:58Z
The Cook rush for loss of 3 yards - 2024-09-08T19:40:41Z

Also out of curiosity, what URL are you requesting this data from? My responses all lacked the "yardsAfterCatch": 0 for the Kincaid pass which you seem to have.

@nntrn
Copy link
Author

nntrn commented Aug 2, 2025

@guizucolotto

I think I missed something, what call do I get the information from the Stats example at the end of this .md?

https://lm-api-reads.fantasy.espn.com/apis/v3/games/ffl/seasons/2025?view=chui_default_platformsettings

in .settings.statSettings.stats

Output 
[
  {
    "abbrev": "PA",
    "active": true,
    "apiIdentifier": "passing.passingAttempts",
    "averagable": false,
    "derived": false,
    "description": "Each Pass Attempted",
    "display": true,
    "displayAbbrev": "PA",
    "displayOrder": 7,
    "displaySortReversed": false,
    "gamePlayedMarker": false,
    "id": 0,
    "pointsScoringEligible": true,
    "rotoScoringEligible": false,
    "statCategoryId": 0,
    "statTypeId": 0,
    "strictSlotStatLimit": false
  },
  ...
  {
    "abbrev": "PYPG",
    "active": true,
    "apiIdentifier": "passing.passingYardsPerGame",
    "averagable": false,
    "derived": true,
    "description": "Passing Yards Per Game",
    "display": false,
    "displayAbbrev": "PYPG",
    "displayOrder": 156,
    "displaySortReversed": false,
    "gamePlayedMarker": false,
    "id": 22,
    "pointsScoringEligible": false,
    "rotoScoringEligible": false,
    "statCategoryId": 0,
    "statDerivation": {
      "defaultInvalid": 0.0,
      "derivedFromStats": {
        "a": 3,
        "b": 210
      },
      "equation": "a / b",
      "invalidStatCheck": null,
      "secondaryDefaultInvalid": null
    },
    "statTypeId": 0,
    "strictSlotStatLimit": false
  },
  ...
]

@KieranMunslow
Copy link

Hi, a specific one regarding the NFL. Is anyone aware of a way to view the correct values for passing yards after catch? Receiving yards after catch seems fine but passing yards after catch I'm struggling to find.

You can get this in the play by play https://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401671764/competitions/401671764/plays?limit=300

This is what I see for Goff btw:

@KieranMunslow

Hi @nntrn, I'm just coming back to this now and I'm struggling to find the 'yardsAfterCatch' field in the play-by-play, even using the URL you've provided. It was definitely there when I first accessed it so confused as to why its seemingly different now.

Any ideas on what might be happening here?

@newadventure079
Copy link

Cannot Tell if Picks are made for College Pick 'em or Pigskin Pick 'em Current Week via ESPN Pick'em API

Problem Summary

I'm using ESPN's Pick'em API to track user picks for challenges like NFL Pigskin Pick'em and College Football Pick'em.

The core issue:
I need to know, each week, whether a user has made their picks before the games start. However, the way the API is structured makes this difficult once the season has started.

Current Behavior

  • Before Week 1:

    • If .picks doesn’t exist: The user hasn’t made any picks.
    • If .picks exists but is empty: The user has submitted picks, but the pick data isn’t available until the games start.

  • After Week 1 & Throughout the Season:

    • The .picks array is a flat list with all picks for the season added as games begin.
    • There’s no breakdown by week (no .picks.week2, .picks.week3, etc.).
    • For example:
      • Just before Week 2, .picks for everyone has 16 entries from Week 1.
      • There are no empty or null entries for future weeks.
      • As Week 2 games start, new picks are revealed, and the array grows (17, 18, 19, ...).
      • There's no way to tell ahead of time if someone has made their picks for the upcoming week; you only find out after kickoff, when it’s too late for users to make the picks for the week.

Ideal vs. Actual Data Structure

Ideal structure (week-by-week distinction):

{
  "picks": {
    "week1": [...],
    "week2": [...],
    // etc.
  }
}

Actual structure (flat array, no week info):

{
  "picks": [
    {...}, // week 1
    {...}, // week 1
    // ... (only fills as games start, no separation by week)
  ]
}

API URLs

  • College Football Pick'em:
    https://gambit-api.fantasy.espn.com/apis/v1/challenges/college-football-pickem-2025/entries/{user_guid}
  • NFL Pigskin Pick'em:
    https://gambit-api.fantasy.espn.com/apis/v1/challenges/nfl-pigskin-pickem-2025/entries/{user_guid}

What I Want

Is there any way, using the current ESPN Pick'em API, to determine before kickoff whether a user has or hasn't made their picks for a given week during the season?

  • Right now, I can only detect an empty/null picks list at the very start of the season (before Week 1).
  • After that, the .picks array grows each week, and there's no way to distinguish “not made picks for this week yet” from simply “picks for this week aren’t public yet”—until it’s already too late.

Before the pick ems site redesign a few years ago, ESPN provided this information. If you viewed a person's picks entry, it would say "Chuck has not made their picks yet", but this functionality was removed in the redesign

Question

Is this a current limitation of the API, or is there a workaround to detect per-week pick completion before games start?

Thank you!

@JamesSingleton
Copy link

Is there a way to get Men's and Women's College Basketball week data? For example, https://site.api.espn.com/apis/common/v3/sports/football/college-football/seasons?startingseason=2023 will give me a weeks array with the number and their start and end date. However, https://site.api.espn.com/apis/common/v3/sports/basketball/mens-college-basketball/seasons?startingseason=2023 does not give me any of that data.

@bkohler96
Copy link

Concerning the NFL only, Does anyone know any other status text ESPN uses to signify whehter a game is live in progress or not other than these?

  "STATUS_SCHEDULED" ,
  "STATUS_IN_PROGRESS",
  "STATUS_HALFTIME",
  "STATUS_END_PERIOD",
  "STATUS_FINAL"

For example is there a STATUS_OVERTIME or *_OVER_TIME maybe? Or STATUS_POST_PONED? etc...

thanks!

I don't know of any official list but just discovered there's a "STATUS_DELAYED" from the Panther / Jags game with a weather delay right now!

@JimNayzium

@JamesSingleton
Copy link

For college football, is there a way to get stats per week per division? For example, for FBS I want to see the passing yards leader, touchdown leader, sack leader, etc etc.

@dnielso5
Copy link

dnielso5 commented Sep 8, 2025

anyone know how i could pull play by play info by player?

I have a script that knows my yahoo player ID, i want to pull their latest play and have it display, similar to yahoos gamelog when viewing your matchup.

@aloktomarr
Copy link

Hi Guys,
Happy to see this detailed doc. Found out just what I was looking for!
Did you guys make espn API key from espn website.
Could you help me with the information of where could I get the api key for getting data from these endpoints.

@dnielso5
Copy link

dnielso5 commented Oct 9, 2025

For ESPN you don't need an API key at least for what i do, this is what i use to pull information for a specific game

https://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/EVENT_ID/competitions/EVENT_ID/plays?limit=300

Replace both "EVENT_ID" with the specific game ID and then this link would pull up that game with the last 300 plays. you can edit the "limit" to make get more or less plays.

https://sports.core.api.espn.com/v2/sports/football/leagues/nfl/events/401547515/competitions/401547515/plays?limit=300

@aloktomarr
Copy link

Thanks a ton! Savior!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment