Authentication Error

--- updatedAt: 2026-09-09T06:49:48.000Z agentTools: siteIndex: https://developer.sportradar.com/llms.txt projectIndex: https://developer.sportradar.com/football/llms.txt --- # API Basics Sportradar's NFL data is delivered as a RESTful B2B (Business-to-Business) API. HTTP requests are made using the [API authentication](https://developer.sportradar.com/getting-started/docs/authentication) access established in [your account](https://developer.sportradar.com/getting-started/docs/your-account), and data can be returned in either JSON or XML format. The NFL API is a Sportradar [League-Based API](https://developer.sportradar.com/getting-started/docs/coverage-information#-league-specific--general-sport-apis). This means it was designed specifically for the sport of football, with the aim of providing our media customers with in-depth, intuitive, and speedy NFL statistics. This page covers the practical basics of the NFL API: authentication, URL structure, seasons and season types, formats, errors, cache behavior, time values, and delivery options. The payloads themselves are covered in the scenario pages; the season model, league structure, and coverage concepts are on [NFL Fundamentals](https://developer.sportradar.com/football/docs/nfl-ig-fundamentals).
*** ## Authentication Every request is authenticated with your API key in the **`x-api-key` header**: ```http GET https://api.sportradar.com/nfl/official/trial/v7/en/league/hierarchy.json x-api-key: YOUR_API_KEY ``` Keep the key server-side; do not embed it in client applications. To accept data from our API feeds, ensure that your application also: * Supports TLS 1.2 or above * Can follow an HTTP redirect (used in [Push](https://developer.sportradar.com/football/docs/nfl-ig-push) and the [Images API](https://developer.sportradar.com/images-and-editorials/reference/images-overview))
*** ## Base URL and URL Structure All REST requests follow one URL shape: ```http GET https://api.sportradar.com/nfl/official/{access_level}/v7/{language_code}/{feed}.{format} ``` * `access_level`: `trial` or `production`, matching your key. * `language_code`: `en` (English). Each endpoint reference page lists the other language codes that feed accepts. * `format`: `json` or `xml`. Both carry the same data on every feed. The NFL API organizes its data into logical endpoints, or feeds: 30+ distinct feeds, each with a focused purpose to allow for efficient data retrieval. To access a team schedule you retrieve a "schedule" feed such as Season Schedule; to access a game you retrieve a "game" feed such as Game Play-by-Play or Game Statistics. Depending on your specific need, different feeds and pull frequencies will be needed. Use our NFL Endpoints section for feed documentation and an interactive sandbox. Most feeds take a unique ID or parameter in the path: a season year and season type, a week number, a date, or a game, team, player, or tournament ID. To retrieve these IDs you may have to iterate through feeds with larger data sets; see our [ID Handling](https://developer.sportradar.com/football/docs/nfl-ig-id-handling) section for more info on Sportradar IDs, and the API map below for which identifier each feed takes.
### Versioning The current version of the NFL API is v7. We strongly recommend using the latest version of all of our APIs, as these will be the most stable and robust offerings. However, we do support up to 3 versions (the current and 2 past versions) of our data APIs, per our [Versioning Policy](https://developer.sportradar.com/getting-started/docs/versioning). To access NFL v7, use `v7` in each request to the API in the `version` parameter (the `v7` segment of the URL shape above). To access previous versions, alter to `v6` or `v5`. No other adjustment is necessary for access.
### Related Football APIs We provide three additional football data APIs: NCAA Football, UFL, and Global American Football. The NCAA Football and UFL APIs have the exact same structure as the NFL, with the only differences being those necessitated by the league structures themselves. For example, Rankings data in NCAA Football behaves differently than Standings in the NFL. And overtime rules in the UFL require slightly different data points at a game level from the NFL API. The Global American Football API is a separate structure, adhering to our [General Sport API](https://developer.sportradar.com/getting-started/docs/coverage-information#-league-specific--general-sport-apis) format. Integration with the "Global" API is not covered in this guide.
*** ## NFL API Map Here is a retrieval path for a player profile.

Player Profile Retrieval Path three requests from a cold start

1. Team id League Hierarchy ⇄ Teams either feed lists every team; take the team id

2. Player id Team Profile request with the team id; the roster carries each player id

3. Player detail Player Profile biographical info, draft info, and seasonal stats

ID Handling covers the ID families; each endpoint reference page lists the fields the feed carries.

All NFL API feeds follow this pulling logic. Visit our [Integration Scenarios](https://developer.sportradar.com/football/docs/nfl-ig-scenarios) section for specific retrieval scenarios. The map below shows how the entire API is interconnected; every pill links its endpoint reference page: {`

`}
*** ## Seasons and Season Types `{season_year}` is the calendar year in which the season begins. `{season_type}` selects the phase: `PRE` (preseason), `REG` (regular season), or `PST` (postseason). Season year plus season type address every seasonal feed, and `{week_number}` narrows the weekly feeds within them. The Seasons feed is the catalog of every season on file; [NFL Fundamentals](https://developer.sportradar.com/football/docs/nfl-ig-fundamentals) walks through the season model, including how far back each season type reaches and how the postseason bracket is also addressed as a tournament.
*** ## Complete Responses Feeds return the complete data set for their scope in a single response, and no NFL endpoint uses pagination. A full Season Schedule, for example, returns every game of the season (272 games in the 18-week regular season) in one payload, and each response provides all data available for the request.
*** ## Errors * **Authentication failures** return **`403`** with an HTML page, not a JSON or XML error object; branch on the status code: ```html 403 (invalid key) Authentication Error

Authentication Error

``` * **Rate-limit errors** return **`429 Too Many Requests`**; slow your request rate and retry, increasing the wait between attempts * **`404`** indicates an unknown ID or path * Other statuses follow the [Response Codes](https://developer.sportradar.com/getting-started/docs/response-codes) page
*** ## Cache Behavior Each REST response carries a `Cache-Control` header stating how long the payload may be served from cache, for example `Cache-Control: public, must-revalidate, max-age=300` (a TTL of 300 seconds). TTLs are tiered by feed family and by game activity: the game feeds move from 60 seconds while a game is `scheduled` to 3 seconds while it is `inprogress`, 600 seconds once it is `closed`, and 4 hours seven days after that, while standings hold a 10-minute cache with the data updating as games conclude. TTL is an upper bound, not a guarantee: when the underlying data changes, the cached object is replaced immediately, even if the TTL has not expired. The per-feed chart is on the [Update Frequencies](https://developer.sportradar.com/football/docs/nfl-ig-update-frequencies) page. ### A TTL Is Not a Polling Recommendation A short TTL means the payload can change that often, not that you should request it that often. Check the header on each response you receive, and match your polling cadence to the freshness your product actually needs. Recommended cadences are on the [Update Frequencies](https://developer.sportradar.com/football/docs/nfl-ig-update-frequencies) page and in each scenario's Best Practices.
*** ## Time Values Timestamps are **UTC** ISO 8601: `scheduled` values carry an explicit `+00:00` offset, and change-log `last_modified` values use the `Z` suffix. Date-only fields such as season dates carry no time zone. The date-scoped feeds (Daily Change Log, Daily Transactions) are keyed to the **league-defined day** rather than the UTC calendar day: both feeds state their window in `start_time` and `end_time` (`04:00:00Z` to `03:59:59Z` the next morning), so a change entered on a US evening belongs to that US date's feed even when its UTC timestamp has rolled past midnight. Plan date math accordingly.
*** ## Delivery Options All NFL data is collected by Sportradar's expert in-house operators and delivered two ways.
### RESTful and Push Most of our NFL endpoints are RESTful, but we also include complementary [Push feeds](https://developer.sportradar.com/football/docs/nfl-ig-push) available for Realtime customers. With RESTful feeds, a request must be made whenever a data update is needed. For our Push feeds, one request will open up a streaming connection. Data is then delivered in a continuous stream indefinitely. Push feeds correlate to the RESTful endpoints, but are not necessarily 1:1 in parity. For example, the Push Events feed follows the same format, and includes nearly all of the same data, as the Game Play-by-Play RESTful endpoint. And Push Statistics correlates to Game Statistics. For increased data speed, and fewer API requests, many customers use Push. Though it is important to note that Push feeds are not meant to replace the RESTful data, but to enhance it. RESTful feeds should always be used as the backbone of the NFL API. See our [Push Feeds](https://developer.sportradar.com/football/docs/nfl-ig-push) section for more info.
### Change Log The NFL API includes a Daily Change Log feed, which is used to catch updates for teams, players, game stats, schedules, and standings. A request is made for a specific date, which then returns a list of unique IDs and timestamps of updates on that day. You can then use these IDs to retrieve stat updates from other endpoints. This allows for quick and efficient data retrieval, and is a common concept across all integration scenarios. See our [Monitoring Data Changes](https://developer.sportradar.com/football/docs/nfl-ig-daily-change-log) guide for detail on how to efficiently leverage this feed.
*** ## Integration Resources * **Interactive reference**: every endpoint in the NFL Endpoints section can be exercised against your key from its reference page * **Postman**: our entire Media APIs are available on Postman; follow or fork the [NFL API v7 collection](https://app.getpostman.com/run-collection/17203961-89640c6c-af84-43c1-abd7-caf50d30a08c?action=collection%2Ffork\&collection-url=entityId%3D782198-7634cb11-9938-4bb6-a255-4f4c94e5738c%26entityType%3Dcollection%26workspaceId%3Da6193b92-ee53-4979-bbfe-7ffdc589c3fc) to receive updates * **XSD schemas**: the [NFL v7 schema](https://api-docs.sportradar.us/NFL/NFL_v7.zip) zip file holds the entire NFL API v7 XSD schema, which describes the XML format * **Simulations**: [replay past games on demand](https://developer.sportradar.com/getting-started/docs/simulations) to exercise live-game handling at any time of year, including the Push feeds * **MCP server**: the [Sportradar MCP server](https://developer.sportradar.com/getting-started/docs/mcp-server) exposes the NFL feeds to AI-assisted development tools * **Questions**: check our NFL API FAQ or reach out to our support team at