Probabilities API Basics

This page covers the practical basics of the Probabilities API: authentication, URL structure, the discovery walk, pagination, and errors. The probability payloads themselves are covered in the two scenario pages.

Authentication

Every request is authenticated with your API key in the x-api-key header:

GET https://api.sportradar.com/probabilities/trial/v1/en/sports.json
x-api-key: YOUR_API_KEY

Keep the key server-side; do not embed it in client applications.

Base URL and URL Structure

All requests go to https://api.sportradar.com/probabilities/ with the version v1:

GET https://api.sportradar.com/probabilities/{access_level}/v1/{language_code}/{feed}.{format}

The placeholders are access_level (trial or production), language_code (English, en, is the fully supported language), and format (json or xml). Both formats carry the same data on every feed.

The Discovery Walk

Eight feeds make up the API, and they chain by ID:

Feed	Takes	Returns
Sports	nothing	Sport IDs
Sport Competitions	sport ID	Competitions with `live_coverage` flag, `current_season_id`, and League Specific GUIDs (`uuids`)
Sport Schedule	sport ID and date	The day's events with probabilities inline
Competition Seasons	competition ID	The current season's ID
Sport Event Probabilities	sport event ID	Current probabilities for one event
Sport Event Probabilities Timeline	sport event ID	Every probability change for the event
Seasonal Probabilities	season ID	Probabilities for the season's events (paginated)
Seasonal Outright Probabilities	season ID	Title, division, and playoff-reach probabilities

Competition Seasons lists the current season, and the seasonal feeds cover that season. The walk at a glance, by the ID each step hands the next:

The Discovery WalkStart at Sports, branch by date, event, or season

StartSports→Sport Competitionslive_coverage, current_season_id, uuids

By dateSport Schedulethe day's events with probabilities inline

By eventSport Event Probabilities→Timelinecurrent figure, then the full curve

By seasonCompetition Seasons→Seasonal ProbabilitiesSeasonal Outright Probabilities

Every feed shares the sr: identifier scheme with the Odds Comparison APIs, so IDs discovered here work there and back.

The Sport Competitions response carries everything needed to branch into either scenario:

GET https://api.sportradar.com/probabilities/trial/v1/en/sports/sr:sport:3/competitions.json
x-api-key: YOUR_API_KEY

{
  "generated_at": "2026-07-20T16:30:50+00:00",
  "competitions": [
    {
      "id": "sr:competition:109",
      "name": "MLB",
      "gender": "men",
      "uuids": "2ea6efe7-2e21-4f29-80a2-0a24ad1f5f85,2fa448bc-fc17-4d3d-be03-e60e080fdc26,fbe91704-36df-4e7c-864a-06d236425999",
      "current_season_id": "sr:season:134469",
      "live_coverage": true
    },
    {
      "id": "sr:competition:803",
      "name": "MLB All Star Game",
      "gender": "men",
      "current_season_id": "sr:season:143236",
      "live_coverage": true
    }
  ]
}

The response is trimmed to two competitions. live_coverage: true means every event in the competition recalculates in play (competitions without the flag can still cover individual events live; check sport_event_status.live per event); current_season_id feeds the seasonal scenario; the comma-separated uuids are the competition's GUIDs in the League Specific APIs (see ID Handling).

Pagination

Seasonal Probabilities paginates with start and limit (limit up to 200, which is also the default page size); read the X-Max-Results, X-Offset, and X-Result headers and walk start until a page returns fewer than limit rows. The other feeds return their full payload in one response.

Errors

Authentication failures return 403 with an HTML "Authentication Error" page, not a JSON error object; branch on the status code
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 page

Cache Behavior

Every response carries a cache-control header stating its TTL. Per-feed values and recommended polling cadences are on Update Frequencies; a short TTL is not a polling recommendation, so check each response's own header and match your cadence to the freshness your product needs.

Time Values

All timestamps are UTC ISO 8601. Date-scoped feeds use the UTC date, so a US evening slate lands on the following UTC date. Each probability point carries its own last_updated timestamp.