Getting Started
Coverage MatrixChange LogLog InContact Us
Getting Started
Coverage MatrixChange LogLog InContact Us
Start typing to search…

API Authentication & Headers

Learn how to access Sportradar APIs using API keys, manage account authorization, and interpret the response headers returned by our feeds.

Authentication

Sportradar APIs use API key authentication as your unique identifier to allow access. Use your API key in the header of each request.

API keys are randomly generated 40 characters. Please note that keys from our previous system are 24 characters.


Sample Requests

Below are example requests using API key authentication in the header.

NFL API

curl --request GET \
     --url https://api.sportradar.com/nfl/official/trial/v7/en/games/2024/REG/schedule.json \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'
require 'uri'
require 'net/http'

url = URI("https://api.sportradar.com/nfl/official/trial/v7/en/games/2024/REG/schedule.json")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["x-api-key"] = 'YOUR_API_KEY'

response = http.request(request)
puts response.read_body
import requests

url = "https://api.sportradar.com/nfl/official/trial/v7/en/games/2024/REG/schedule.json"

headers = {
    "accept": "application/json",
    "x-api-key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)

print(response.text)

Soccer API

curl --request GET \
     --url https://api.sportradar.com/soccer/trial/v4/en/competitions.json \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'
require 'uri'
require 'net/http'

url = URI("https://api.sportradar.com/soccer/trial/v4/en/competitions.json")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["x-api-key"] = 'YOUR_API_KEY'

response = http.request(request)
puts response.read_body
import requests

url = "https://api.sportradar.com/soccer/trial/v4/en/competitions.json"

headers = {
    "accept": "application/json",
    "x-api-key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)

print(response.text)

For proper syntax of each endpoint, visit the API Endpoint docs (NFL, Soccer).


Authorization

To authorize to our APIs you need to create an account. Sign up for a free trial or access your existing account here.

Within each application on your account is a unique master API key that is applicable across all products associated with that application. These may be licensed products or free trials.

For more information on accounts and access, see our Account Info section.


Headers

This section outlines the response headers used across our API suite and how they should be interpreted. While a common set of standard HTTP headers is shared across most APIs, some headers vary by feed based on how data is generated, cached, and delivered.

Certain headers reflect the state of the cached item, while others indicate when the underlying data itself was last updated. These distinctions are critical for evaluating cache behavior, data freshness, and re-ingestion strategies. The sections below describe the standard headers present on all APIs, followed by feed-specific and API-specific variations.


Standard Headers

date
The timestamp generated by the server at the time the API response is returned. This reflects when the response was processed by the delivery infrastructure, not necessarily when the underlying data was last updated.

etag
An HTTP standard header that uniquely identifies a specific version of a resource. It is used to determine whether the content has changed between requests. If the ETag value differs from a previously stored value, the full payload should be re-ingested to obtain the latest version of the resource.

x-cache
A CloudFront-generated header indicating how the response was served. Common values include Hit from CloudFront (served directly from the edge cache) and Miss from CloudFront (fetched from the origin). You may also see RefreshHit from CloudFront, which indicates that the object existed in the cache but was considered stale, prompting CloudFront to revalidate it with the origin. This header is useful for validating edge cache behavior and overall cache efficiency.

Sample
HTTP/2 200
content-type: application/json
content-length: 8772
x-amzn-trace-id: Root=1-69385908-00661d4d50896329349bfc16;Parent=185dca3385ee1f59;Sampled=0;Lineage=1:4b1cd4fb:0
x-amzn-requestid: 8a71886b-41b8-4abd-8fc1-2ba31233e1e5
last-modified: Wed, 03 Dec 2025 22:38:41 GMT
x-generated-date: Tue, 21 Oct 2025 13:10:58 GMT
x-amzn-remapped-content-length: 8772
x-amz-apigw-id: VVLZWFr9oAMES1Q=
via: 1.1 d125bf8405e840aa51a88ae3d8d91fb2.cloudfront.net (CloudFront), 1.1 202eceb25387048bc093cf2084e5cea6.cloudfront.net (CloudFront)
x-amz-cf-pop: IAD12-P1
date: Wed, 10 Dec 2025 13:19:30 GMT
cache-control: public, max-age=7201
expires: Wed, 10 Dec 2025 15:19:31 GMT
etag: "5a34494c9088ec1ca133a81a30d8a96a"
vary: Accept-Encoding
x-cache: Hit from cloudfront
x-amz-cf-pop: IAD61-P4
x-amz-cf-id: 59n473G40tav0Rab0AvEpWm7mTUVn0xywRFP4NACVJsh8mYa7P8ESw==
age: 6692

Headers for League-Specific APIs

The below header info relates to the following APIs:

  • NBA, NBA G League, WNBA, NCAAMB, NCAAWB, Unrivaled, NFL, UFL, USFL, NCAAFB, MLB, NHL, NCAAMH

last-modified
An HTTP standard header indicating the date and time at which the resource was last modified on the server. For these APIs, it reflects the last time the object stored in Amazon S3 was updated when the versioned and translated XML or JSON file was built.

x-generated-date
A custom response header that represents the date and time when the upstream data source last generated or refreshed the data. This timestamp corresponds to the freshness of the underlying dataset itself and may differ slightly from Last-Modified.

cache-control
An HTTP standard header that defines caching directives for both CloudFront and client-side caches. For example, public, max-age=121 indicates the response may be stored by any cache and is considered fresh for 121 seconds before revalidation is required.

Sample
HTTP/2 200
content-type: application/json
content-length: 8772
x-amzn-trace-id: Root=1-69385908-00661d4d50896329349bfc16;Parent=185dca3385ee1f59;Sampled=0;Lineage=1:4b1cd4fb:0
x-amzn-requestid: 8a71886b-41b8-4abd-8fc1-2ba31233e1e5
last-modified: Wed, 03 Dec 2025 22:38:41 GMT
x-generated-date: Tue, 21 Oct 2025 13:10:58 GMT
x-amzn-remapped-content-length: 8772
x-amz-apigw-id: VVLZWFr9oAMES1Q=
via: 1.1 d125bf8405e840aa51a88ae3d8d91fb2.cloudfront.net (CloudFront), 1.1 202eceb25387048bc093cf2084e5cea6.cloudfront.net (CloudFront)
x-amz-cf-pop: IAD12-P1
date: Wed, 10 Dec 2025 13:19:30 GMT
cache-control: public, max-age=7201
expires: Wed, 10 Dec 2025 15:19:31 GMT
etag: "5a34494c9088ec1ca133a81a30d8a96a"
vary: Accept-Encoding
x-cache: Hit from cloudfront
x-amz-cf-pop: IAD61-P4
x-amz-cf-id: 59n473G40tav0Rab0AvEpWm7mTUVn0xywRFP4NACVJsh8mYa7P8ESw==
age: 6692

Variations on Other APIs

Some APIs expose different cache behavior or additional headers based on how the backend content is generated and served:

cache-control
On other APIs, such as Soccer or Tennis, Cache-Control governs both how long the response is cached at the edge and how long it may be retained by the backend before new content is generated. This differs from validation-based models where upstream content is checked for freshness without being regenerated on each miss.

x-amzn-remapped-date
A header added by Amazon API Gateway when it rewrites the Date header on the response. The original Date value from the upstream service is preserved and surfaced as x-amzn-Remapped-Date, allowing both timestamps to be inspected for debugging and timing analysis.

Sample
HTTP/2 200
content-type: application/json
content-length: 1615262
date: Wed, 10 Dec 2025 15:04:12 GMT
x-amzn-requestid: 1ff66d0c-7c53-4670-ad3e-ad6a3a7cecfa
x-backend-type: L
x-offset: 0
x-amz-apigw-id: VYLMXEnVliAEINA=
cache-control: max-age=300, public, s-maxage=300
x-result: 100
etag: "2ef32e07b8e5b50c59c56b6967b9e5b9"
x-max-results: 386
link: {'<https://schemas.sportradar.com/sportsapi/soccer/v4/schemas/season_summaries.json#>'}; rel="describedBy"
x-amzn-trace-id: Root=1-69398be8-480bbe276e529522204bba7a
x-amzn-remapped-date: Wed, 10 Dec 2025 15:04:12 GMT
vary: Accept-Encoding
x-cache: Hit from cloudfront
via: 1.1 2cd91b399d7db009d02ca3e5944f2eca.cloudfront.net (CloudFront)
x-amz-cf-pop: IAD61-P4
x-amz-cf-id: zm4OTA2paCdFHI8r0sQAE4fm7Ogj6N\_FYjjqXMbIYEney1dEkmd6xQ==
age: 31


Updated 15 days ago

© Sportradar AG, St. Gallen, Switzerland