Spotrac APIspotrac.com ↗
Access NFL player contracts, cap hits, roster salary data, and team information from Spotrac via a structured JSON API. Covers all 32 teams.
What is the Spotrac API?
The Spotrac API provides structured access to NFL salary cap and contract data across 4 endpoints, covering all 32 teams and individual player financials. Use get_player_contract to retrieve year-by-year cap hits, base salaries, signing bonuses, and dead cap figures for any player, or get_team_roster to pull a full team's salary cap roster for a given year. Player and team identifiers are consistent across endpoints, making it straightforward to join roster data with individual contract details.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/1063a484-f52f-4db5-a50f-b26705848e2f/list_nfl_teams' \ -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 spotrac-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.
"""Spotrac NFL API — salary cap and contract data for all 32 NFL teams."""
from parse_apis.spotrac_nfl_api import Spotrac, PlayerNotFound
client = Spotrac()
# List all NFL teams — single-page, returns 32 teams.
for team in client.teams.list(limit=5):
print(team.name, team.slug)
# Construct a team by slug and list its roster for a given year.
chiefs = client.team("kansas-city-chiefs")
player = chiefs.players.list(year=2024, limit=1).first()
if player:
print(player.name, player.player_id, player.player_slug)
# Drill into a player's full contract from the roster.
if player:
contract = player.contract()
print(contract.name, contract.player_id)
for table in contract.tables[:2]:
print(table.title, table.headers[:4])
# Search for a player across all sports by name.
result = client.players.search(query="Travis Kelce", limit=3).first()
if result:
print(result.name, result.player_id)
# Typed error handling for a missing player.
try:
bad = client.playercontracts.get(player_id="9999999")
print(bad.name)
except PlayerNotFound as exc:
print(f"Player not found: {exc.player_id}")
print("exercised: teams.list / team.players.list / player.contract / players.search / playercontracts.get")List all 32 NFL teams with their slugs. Each team slug is the stable identifier used to fetch rosters and other team-scoped data. Returns the full league regardless of parameters.
No input parameters required.
{
"type": "object",
"fields": {
"teams": "array of team objects with name, slug, and url"
},
"sample": {
"data": {
"teams": [
{
"url": "https://www.spotrac.com/nfl/buffalo-bills",
"name": "Buffalo Bills",
"slug": "buffalo-bills"
},
{
"url": "https://www.spotrac.com/nfl/kansas-city-chiefs",
"name": "Kansas City Chiefs",
"slug": "kansas-city-chiefs"
}
]
},
"status": "success"
}
}About the Spotrac API
Team and Roster Coverage
The list_nfl_teams endpoint returns all 32 NFL teams, each with a name, slug, and url. The slug field (e.g. kansas-city-chiefs, buffalo-bills) is the stable identifier passed to get_team_roster as the required team_slug parameter. get_team_roster accepts an optional year integer, letting you pull historical roster salary pages rather than only the current season. Each player object in the response includes name, player_id, player_slug, and url.
Player Contract Details
get_player_contract returns the most detailed financial data in the API. The response includes a tables array where each table has a title, headers, and rows — representing breakdowns such as cap hit by year, base salary, roster bonuses, option bonuses, signing bonuses, and dead cap. The position field returns the player's abbreviated position (e.g. QB, WR). Passing both player_id and the optional player_slug together ensures faster resolution without a redirect lookup; the player_id alone is sufficient if the slug is unavailable.
Player Search
search_players accepts a query string (player name) and returns matching records with name, player_id, position, and url. Results may include trending players alongside direct name matches and cover all sports tracked by Spotrac, not just NFL — so callers should filter by position or cross-reference with get_team_roster data when NFL-only results are required.
Identifiers and Cross-Endpoint Usage
The player_id returned by both search_players and get_team_roster is the same numeric string used as the required input to get_player_contract. This makes the typical workflow: search or fetch a roster to get IDs, then call get_player_contract per player for the full financial breakdown.
The Spotrac API is a managed, monitored endpoint for spotrac.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when spotrac.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 spotrac.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 salary cap tracker that aggregates cap hits across all 32 teams using
get_team_rosterandget_player_contract. - Compare dead cap figures for released players by parsing the dead cap table returned in
get_player_contract. - Retrieve historical roster salary data for a specific team-year by passing the
yearparameter toget_team_roster. - Look up signing bonus and option bonus schedules for free agency research using the
tablesarray in contract responses. - Power a fantasy sports tool with real contract values and cap hit data tied to player positions from
search_players. - Identify players with the highest base salary in a given year by pulling roster data and joining with individual contract breakdowns.
- Monitor year-over-year changes in a player's cap hit by querying
get_player_contractacross multiple seasons.
| 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 Spotrac have an official developer API?+
What financial fields does `get_player_contract` return?+
tables array containing named tables — typically covering cap hit, base salary, signing bonuses, roster bonuses, option bonuses, and dead cap — each with headers and year-by-year rows. The exact tables present vary by player and contract structure. Top-level fields also include name, team, position, player_id, and player_slug.Does `search_players` return only NFL players?+
search_players covers all sports tracked by Spotrac, which includes NFL, NBA, MLB, NHL, and others. Results include position and url, which can be used to filter for NFL-specific entries. For a confirmed NFL-only player list, use get_team_roster with a known team_slug from list_nfl_teams.Does the API cover NBA, MLB, or NHL contract data?+
search_players may return non-NFL athletes in results, but there are no roster or contract endpoints for other leagues. You can fork the API on Parse and revise it to add endpoints covering other sports that Spotrac tracks.Is there a way to get contract data for all players on a team in a single call?+
get_team_roster returns player IDs and slugs for the full roster, but individual contract financials require a separate get_player_contract call per player. You can batch these calls using the player_id values from the roster response. You can fork the API on Parse and revise it to add a bulk contract endpoint if per-player iteration is too slow for your use case.