---
title: "ELO trajectory for a season"
method: GET
path: "/v1/ratings/{sport}/history"
tags: ["ratings"]
---

# ELO trajectory for a season

`GET /v1/ratings/{sport}/history`

## Request

- Base URL: `https://api.predixsport.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.predixsport.com/v1/ratings/{sport}/history`
- Auth: none declared

Returns the ELO trajectory written by each ratings-pipeline run. NBA, EuroLeague and football give one point per team per matchday, ordered by date; tennis and wta give one point per player per match (a per-match Elo log), ordered by player then date. Trajectories are season-scoped; `rating_basis` in the response tells you how to read them — "season_relative" (top-flight football, EuroLeague) and "absolute" (NBA) both re-seed at 1500 each season (the NBA label refers to its fixed 1500-anchored scale, not to cross-season carryover), while second-division football seeds each season from the previous one regressed toward the mean ("carryover"). Tennis and wta are "points_seeded": season-scoped Elo re-seeded from tour entry points every January — never compare across seasons. Football history is league-scoped: the `league` parameter is required. Filter with `team` (substring of the team name; for tennis and wta this is the player-name filter and is strongly recommended, since a whole season is thousands of per-match rows; EuroLeague also accepts the club code) and `from`/`to` dates; page with `limit`/`offset` and `has_more`. The ratings dataset is published under CC BY 4.0 — reuse is welcome with a link to predixsport.com.

## Path parameters

- `sport` 'nba' | 'euroleague' | 'football' | 'tennis' | 'wta' | 'champions', required

## Query parameters

- `season` string, nullable: Season as stored in the AI pipeline ("2026" for NBA/tennis/wta, "2025_2026" for football, "E2025" for EuroLeague). Defaults to the most recent on file.
- `league` 'serie_a' | 'premier_league' | 'la_liga' | 'bundesliga' | 'ligue_1' | 'championship' | 'league_one' | 'league_two' | 'segunda_division' | 'ligue_2' | 'bundesliga_2' | 'serie_b'
- `team` string, nullable: Filter to teams whose name contains this text (EuroLeague also matches the exact club code, e.g. 'MAD'). For tennis and wta this is the player-name filter — strongly recommended, as a whole season is thousands of per-match rows.
- `from` string, date, nullable: Earliest matchday (YYYY-MM-DD), inclusive.
- `to` string, date, nullable: Latest matchday (YYYY-MM-DD), inclusive.
- `limit` integer: Points per page (a league season is ~800 points, an NBA season ~2,500).
- `offset` integer

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- union
  - NBARatingsHistoryResponse
    - `season` string, required
    - `rating_basis` 'absolute'
    - `count` integer, required: Points in this page.
    - `has_more` boolean, required: True when further pages exist — advance `offset`.
    - `license` string: Ratings-data license. Reuse permitted with attribution: link to https://www.predixsport.com
    - `attribution` string
    - `sport` 'nba'
    - `points` NBARatingHistoryPoint[], required
      - `date` string, date, required: Matchday the rating was computed for.
      - `team_name` string, required
      - `elo_rating` number, required: ELO after the matchday, on the fixed 1500-anchored scale (every team re-seeds at 1500 at the start of each season).
      - `matches_played` integer, required
      - `position_overall` integer, required: League-wide rank by ELO on that matchday.
  - EuroLeagueRatingsHistoryResponse
    - `season` string, required
    - `rating_basis` 'season_relative'
    - `count` integer, required: Points in this page.
    - `has_more` boolean, required: True when further pages exist — advance `offset`.
    - `license` string: Ratings-data license. Reuse permitted with attribution: link to https://www.predixsport.com
    - `attribution` string
    - `sport` 'euroleague'
    - `points` EuroLeagueRatingHistoryPoint[], required
      - `date` string, date, required: Game date the rating was computed for.
      - `team_code` string, required: Three-letter EuroLeague club code.
      - `team_name` string, required
      - `elo_rating` number, required: Season-relative ELO entering the game (resets each season; negative = below the season-start baseline).
      - `matches_played` integer, required
  - FootballRatingsHistoryResponse
    - `season` string, required
    - `rating_basis` 'season_relative' | 'carryover'
    - `count` integer, required: Points in this page.
    - `has_more` boolean, required: True when further pages exist — advance `offset`.
    - `license` string: Ratings-data license. Reuse permitted with attribution: link to https://www.predixsport.com
    - `attribution` string
    - `sport` 'football'
    - `league` string, required: Customer-facing league code (e.g. 'serie_a').
    - `points` FootballRatingHistoryPoint[], required
      - `date` string, date, required: Matchday the rating was computed for.
      - `team_name` string, required
      - `elo_overall_rating` number, required: Overall ELO entering the matchday. Read with `rating_basis`: top-flight leagues reset to the 1500 baseline each season (season_relative); second divisions seed from the previous season, regressed toward the mean (carryover).
      - `matches_played` integer, required
      - `elo_position` integer, required: League rank by overall ELO on that matchday.
  - TennisRatingsHistoryResponse
    - `season` string, required
    - `rating_basis` 'points_seeded'
    - `count` integer, required: Points in this page.
    - `has_more` boolean, required: True when further pages exist — advance `offset`.
    - `license` string: Ratings-data license. Reuse permitted with attribution: link to https://www.predixsport.com
    - `attribution` string
    - `sport` 'tennis'
    - `points` TennisRatingHistoryPoint[], required
      - `date` string, date, required: Match date the rating was computed for.
      - `player_name` string, required
      - `opponent_name` string, required: The other player in the match (as-observed name).
      - `tournament` string, nullable: Tournament the match belonged to (null if unrecorded).
      - `surface` string, nullable: Court surface — hard / clay / grass (null if unrecorded).
      - `won` boolean, required: True if `player_name` won this match.
      - `elo_pre` number, required: Season ELO entering the match (points-seeded each January).
      - `elo_rating` number, required: Season ELO after the match. Season-scoped: it re-seeds from tour entry points every January, so never compare it across seasons.
  - WTARatingsHistoryResponse: WTA (women's tennis) — same per-match ELO-log shape as ATP tennis, read from ``wta_elo_progression``.
    - `season` string, required
    - `rating_basis` 'points_seeded'
    - `count` integer, required: Points in this page.
    - `has_more` boolean, required: True when further pages exist — advance `offset`.
    - `license` string: Ratings-data license. Reuse permitted with attribution: link to https://www.predixsport.com
    - `attribution` string
    - `sport` 'wta'
    - `points` TennisRatingHistoryPoint[], required
      - `date` string, date, required: Match date the rating was computed for.
      - `player_name` string, required
      - `opponent_name` string, required: The other player in the match (as-observed name).
      - `tournament` string, nullable: Tournament the match belonged to (null if unrecorded).
      - `surface` string, nullable: Court surface — hard / clay / grass (null if unrecorded).
      - `won` boolean, required: True if `player_name` won this match.
      - `elo_pre` number, required: Season ELO entering the match (points-seeded each January).
      - `elo_rating` number, required: Season ELO after the match. Season-scoped: it re-seeds from tour entry points every January, so never compare it across seasons.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/predixsport/apis/predixsport-api.md) · [All operations](https://skmtc.dev/predixsport/apis/predixsport-api/llms.txt) · [OpenAPI document](https://skmtc.dev/predixsport/apis/predixsport-api/revisions/02014aee733d?raw)