Stathead APIstathead.com ↗
Get NFL player game-by-game stats from Stathead via one API endpoint. Passing, rushing, receiving, fumbles, and snap counts by season or career.
What is the Stathead API?
The Stathead NFL API exposes one endpoint — football_player_game_finder — that returns up to dozens of response fields per game, covering passing, rushing, receiving, fumble, and snap-count statistics for any NFL player. Look up players by name (e.g., 'Patrick Mahomes') or by their Pro-Football-Reference player ID, then filter by season year and game type to narrow results to regular season or playoff games specifically.
curl -X GET 'https://api.parse.bot/scraper/775182f5-1eae-4d67-81ec-ec47c3612303/football_player_game_finder?year=2024&player=Patrick+Mahomes&game_type=R&player_id=MahoPa00' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace stathead-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Pro-Football-Reference Player Game Stats — bounded, re-runnable walkthrough."""
from parse_apis.pro_football_reference_player_game_stats_api import (
ProFootballReference,
GameType,
PlayerNotFound,
)
pfr = ProFootballReference()
# Fetch a player's 2024 regular-season game log by ID.
log = pfr.gamelogs.find(player_id="MahoPa00", year="2024", game_type=GameType.REGULAR_SEASON)
print(f"{log.player_name} ({log.year}): {log.regular_season_games} regular-season games")
# Iterate over the first few games and print key stats.
for game in log.items[:3]:
print(f" {game.date} vs {game.opp_name_abbr}: {game.pass_yds} pass yds, {game.pass_td} TD, {game.pass_int} INT — rating {game.pass_rating}")
# Fetch by player name (search-resolved) — playoff games only.
playoff_log = pfr.gamelogs.find(player="Patrick Mahomes", year="2024", game_type=GameType.PLAYOFFS)
print(f"\nPlayoffs: {playoff_log.playoff_games} games")
for game in playoff_log.items[:2]:
print(f" {game.date} {game.game_result}: {game.rush_yds} rush yds, {game.rush_td} rush TD")
# Typed error handling: unknown player name.
try:
pfr.gamelogs.find(player="Zzzzz Nonexistent")
except PlayerNotFound as exc:
print(f"\nCaught PlayerNotFound: {exc}")
print("\nExercised: gamelogs.find (by ID, by name, regular season, playoffs, error catch)")
Retrieve game-by-game statistics for an NFL player from Pro-Football-Reference. Accepts either a player name (resolved via search) or a direct PFR player ID. Returns detailed per-game stats including passing (completions, attempts, yards, TDs, INTs, passer rating), rushing (attempts, yards, TDs), receiving (targets, receptions, yards, TDs), fumbles, and snap counts. When year is omitted, returns the full career game log. The game_type filter restricts to regular season or playoff games only.
| Param | Type | Description |
|---|---|---|
| year | string | Season year to get game logs for (e.g., '2024'). If omitted, returns the career game log. |
| player | string | Player name to search for (e.g., 'Patrick Mahomes'). Either player or player_id is required. When multiple players share a name, the first search result is used. |
| game_type | string | Filter by game type. Accepted values: 'R' for regular season only, 'P' for playoffs only. If omitted, returns both regular season and playoff games. |
| player_id | string | Pro-Football-Reference player ID (e.g., 'MahoPa00'). Either player or player_id is required. The ID format is typically the first four letters of the last name + first two of the first name + a two-digit disambiguator. |
{
"type": "object",
"fields": {
"year": "string, season year or 'career'",
"items": "array of game log objects with per-game statistics",
"total": "integer, total number of games returned",
"player_id": "string, PFR player ID",
"player_name": "string, full player name",
"playoff_games": "integer, count of playoff games in the response",
"regular_season_games": "integer, count of regular season games in the response"
},
"sample": {
"data": {
"year": "2024",
"items": [
{
"rec": "1",
"date": "2024-09-05",
"rec_td": "0",
"fumbles": "0",
"pass_td": "1",
"rec_yds": "2",
"rush_td": "0",
"targets": "1",
"pass_att": "28",
"pass_cmp": "20",
"pass_int": "1",
"pass_yds": "291",
"rush_att": "2",
"rush_yds": "3",
"week_num": "1",
"catch_pct": "100.0",
"game_type": "regular_season",
"is_starter": "*",
"game_result": "W, 27-20",
"pass_rating": "101.9",
"pass_sacked": "2",
"fumbles_lost": "0",
"pass_cmp_pct": "71.4",
"opp_name_abbr": "BAL",
"team_name_abbr": "KAN",
"pass_sacked_yds": "10",
"rec_yds_per_rec": "2.0",
"rec_yds_per_tgt": "2.0",
"pass_yds_per_att": "10.4",
"rush_yds_per_att": "1.5",
"snap_counts_off_pct": "100.0",
"snap_counts_offense": "54",
"pass_adj_yds_per_att": "9.5",
"team_game_num_season": "1",
"player_game_num_career": "97"
}
],
"total": 20,
"player_id": "MahoPa00",
"player_name": "Patrick Mahomes",
"playoff_games": 3,
"regular_season_games": 17
},
"status": "success"
}
}About the Stathead API
What the Endpoint Returns
The football_player_game_finder endpoint returns a game-by-game log for a specified NFL player. Each entry in the items array includes the game date, team, opponent, and result alongside a full stat line: passing completions, attempts, yards, touchdowns, interceptions, and passer rating; rushing attempts, yards, and touchdowns; receiving targets, receptions, yards, and touchdowns; fumble counts; and snap statistics. The response also surfaces summary integers — total, regular_season_games, and playoff_games — so you can see the game-type breakdown without counting rows yourself.
Filtering and Lookup
Either the player string (e.g., 'Josh Allen') or the player_id PFR slug (e.g., 'AlleJo02') is required; the two are interchangeable for lookup purposes. The optional year parameter scopes results to a single season; omitting it returns the full career game log. The game_type parameter accepts 'R' for regular season only or 'P' for playoff games only; omitting it returns all game types combined. The response always echoes back the resolved player_id and player_name, which is useful when you query by name and want the canonical PFR identifier for follow-up calls.
Coverage Scope
Data is sourced from Pro-Football-Reference via Stathead, which covers the NFL historical record. Results reflect the statistical categories tracked at the player-game level in that database. Positions that rarely accumulate passing, rushing, or receiving stats — linemen, for example — will return sparse or empty stat fields for those categories, which is accurate to the source data rather than a gap in the API.
The Stathead API is a managed, monitored endpoint for stathead.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when stathead.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official stathead.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a fantasy football tool that pulls a player's game-by-game receiving yards and touchdown totals for a given season.
- Compare a quarterback's regular-season vs. playoff passer rating across their career using the
game_typefilter. - Populate a player profile page with career game logs by querying without a
yearparameter. - Analyze snap-count trends for a running back over multiple seasons to evaluate workload changes.
- Feed a machine-learning model with per-game rushing attempts and yards to predict future performance.
- Track interception rates per game for a quarterback during a specific season using passing attempts and INT fields.
- Verify a player's PFR
player_idby querying with their full name and reading the echoedplayer_idin the response.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Stathead have an official developer API?+
What does the response distinguish between regular season and playoff games?+
regular_season_games and playoff_games integer counts. Each game object in the items array reflects the game_type it belongs to. You can also pre-filter server-side by passing game_type: 'R' or game_type: 'P' so the items array contains only the game type you need.Can I retrieve stats for multiple players in a single call?+
football_player_game_finder endpoint accepts one player lookup per request — either a player name or a player_id. To compare multiple players, you would issue separate requests for each. You can fork this API on Parse and revise it to batch multiple player lookups into a single response.Does the API cover team-level or season-aggregate statistics?+
How fresh is the game log data, and are in-progress games included?+
items array contains completed games with final stat lines.