---
title: "Full NBA match payload (game-level + per-player projections)"
method: GET
path: "/v1/predictions/nba/{match_id}"
tags: ["predictions"]
---

# Full NBA match payload (game-level + per-player projections)

`GET /v1/predictions/nba/{match_id}`

## 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/predictions/nba/{match_id}`
- Auth: none declared

Returns the full payload for a single NBA match identified by ``match_id`` (the `file_name` column on `daily_predictions`, discoverable via the `search` endpoint). Includes winner probabilities on `home_team` / `away_team`, dedicated `predicted_point_diff` (spread regressor) and `predicted_total_points` (total regressor), plus a `players` array — one entry per projected player carrying expected points/rebounds/assists/3PM and the full count PMF for each. Probabilities across families come from independent models — small numeric mismatches are by design. Returns **404** if the `match_id` is unknown. Use `GET /v1/predictions/nba/{match_id}/players` if you only need the player layer.

## Path parameters

- `match_id` string, required

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- NBAMatchDetail
  - `match_id` string, required
  - `sport` 'nba'
  - `prediction_date` string, date, required
  - `season` integer, required
  - `home_team` TeamStats, required: Win-side projection for an NBA team.
    - `name` string, required
    - `win_probability` number, nullable: Probability of this team winning, in [0, 1]. Null when the winner classifier has not been run for this match yet.
  - `away_team` TeamStats, required: Win-side projection for an NBA team.
    - `name` string, required
    - `win_probability` number, nullable: Probability of this team winning, in [0, 1]. Null when the winner classifier has not been run for this match yet.
  - `predicted_point_diff` number, nullable: Expected (home_points - away_points) from the dedicated spread regressor.
  - `predicted_total_points` number, nullable: Expected sum of points scored by both teams (dedicated total regressor).
  - `players` NBAPlayerProjection[]: Per-player projections from the player-props models. Empty list when no player rows exist for this match.
    - `name` string, required
    - `team` string, required
    - `is_home` boolean, required
    - `position` integer, nullable: Rank slot inside the published starting five, 1 to 5, and 0 for a roster player outside it or for a projection made with no published lineup. It is NOT a listed basketball position: read ``listed_position`` and ``court`` for that.
    - `expected_points` number, nullable
    - `expected_rebounds` number, nullable
    - `expected_assists` number, nullable
    - `expected_three_pointers_made` number, nullable: Expected three-pointers made.
    - `points_distribution` object, nullable
    - `rebounds_distribution` object, nullable
    - `assists_distribution` object, nullable
    - `three_pointers_made_distribution` object, nullable
    - `expected_steals` number, nullable
    - `steals_distribution` object, nullable
    - `expected_blocks` number, nullable
    - `blocks_distribution` object, nullable
    - `expected_turnovers` number, nullable
    - `turnovers_distribution` object, nullable
    - `expected_field_goals_made` number, nullable
    - `field_goals_made_distribution` object, nullable
    - `expected_field_goals_attempted` number, nullable
    - `field_goals_attempted_distribution` object, nullable
    - `expected_free_throws_made` number, nullable
    - `free_throws_made_distribution` object, nullable
    - `expected_free_throws_attempted` number, nullable
    - `free_throws_attempted_distribution` object, nullable
    - `expected_nba_salary_cap_points` number, nullable: Expected NBA Salary Cap fantasy score (points + rebounds + 2 x assists + 3 x blocks + 3 x steals) from a model trained on that total directly, not from summing the component models. It is the only projected total with a distribution of its own.
    - `nba_salary_cap_points_distribution` object, nullable
    - `started` boolean, nullable: True when the player is in the team's published starting five for this game, false when a lineup was published and he is not in it, null when no lineup had been published at projection time. Null is a real state here, not a missing value. This is the published lineup and nothing more: it is not a chance of playing and carries no injury information.
    - `projection_mode` string, nullable: gameday (a lineup was published), gameday_no_lineup (the whole roster projected without one) or calendar (a lineup-free projection for a game later in the week). Null for rows written before the full-roster rollout.
    - `row_source` string, nullable: Where the roster row came from: box_score, roster_union or published_lineup.
    - `low_confidence` boolean, nullable: True when this row rests on a thin recent record, typically a roster player with no recent appearance. The row is published flagged rather than dropped.
    - `listed_position` string, nullable: Listed basketball position, e.g. PG, SG, SF, PF, C, G-F.
    - `court` string, nullable: BC for backcourt or FC for frontcourt, derived from the first token of listed_position. Fantasy formats that require a backcourt and frontcourt split use it.
    - `fantasy` NBAFantasyScore: Projected fantasy score for the requested scoring preset.
      - `preset` string, required
      - `label` string, required
      - `expectation` number, nullable: The projected score for this preset. For nba_salary_cap it is the model trained on that total itself, which is the number every Predixsport surface prints and ranks by. For every other points preset it is the preset's scoring formula applied to the component projections, exact for the average by linearity whatever the dependence between the individual stats. Null when any stat the formula needs is missing for this player: a partial total would understate him with nothing here to say so. Always null for yahoo_9cat, which is a per-category league with no single score.
      - `expectation_source` string: Which of the two readings ``expectation`` holds: ``direct_model`` for a preset scored by a model trained on its own total (nba_salary_cap), ``component_formula`` for the linear combination of the component projections, ``none`` when no score could be formed.
      - `formula_expectation` number, nullable: The preset formula applied to the component projections, published alongside ``expectation`` for nba_salary_cap so the two readings of the same total can be compared. It is a cross-check, not a second score: the served number is ``expectation``. Null for every other preset, where the two would be the same value.
      - `distribution_quantiles` object, nullable: Quantiles p10/p25/p50/p75/p90 of the score. Present for nba_salary_cap only, because it is the one preset with a model trained on the total itself. No composite distribution is claimed for the others: a sum of dependent counts is not the convolution of the marginals.
      - `categories` NBAFantasyCategory[], nullable: Per-category values. Present for yahoo_9cat only.
        - `key` string, required
        - `label` string, required
        - `value` number, nullable
        - `lower_is_better` boolean
        - `ratio_of_means` boolean: True for FG% and FT%, which are the ratio of two projected averages rather than a projected percentage. The distinction matters: the expected ratio is not the ratio of expectations.
  - `key_factors` KeyFactors: Concept-level attribution of the winner prediction. Computed with gradient-based attribution on the production neural network and aggregated into human concepts; the factors approximately sum to the gap between the served win probability and an even matchup. For football the factors compare the two sides directly (the draw probability is modelled separately). Absent on rows predicted before the explainability rollout (June 2026).
    - `schema_version` integer: Contract version of this payload.
    - `baseline_probability` number, nullable: Model probability for an average matchup — the reference point the factors move the prediction away from.
    - `factors` KeyFactor[]: Factors sorted by absolute impact (largest first).
      - `key` string, required: Stable identifier of the factor (e.g. 'surface', 'starting_five', 'attack').
      - `label` string, required: Human-readable factor name, as shown on predixsport.com.
      - `prob_points` number, required: How many win-probability percentage points this factor moves the prediction. Positive values favour the first side (player one / home team), negative values the second side.
      - `direction` string, required: What the factor favours: 'player_one'/'player_two' for tennis, 'home'/'away' for NBA and football winner attributions, 'under'/'over' for the football under/over 2.5 attribution.
      - `stable` boolean, required: True when the attribution sign is consistent across independent estimator runs. Treat unstable factors as indicative, not decisive.
      - `display` boolean: False for internal context buckets not shown on predixsport.com.
      - `share` number, nullable: This factor's share of the total absolute attribution (0-1).
      - `synthetic` boolean, nullable: True for fixed baseline terms (home advantage, league scoring environment) that reflect league-wide tendencies rather than this specific matchup.
      - `side` string, nullable: For per-team factors on outcome attributions (football under/over): which team the factor describes ('home'/'away'). Surfaces can substitute the actual team name into the label.
  - `actual` NBAActual: Realized box-score result once the match has been played and reconciled (``in_season_performance``). Absent from the response until the game is played — the predictive fields are unchanged either way.
    - `home_points` number, nullable: Points scored by the home team.
    - `away_points` number, nullable: Points scored by the away team.
    - `point_diff` number, nullable: Realized (home_points - away_points). Compare with predicted_point_diff.
    - `total_points` number, nullable: Realized combined points (home + away). Compare with predicted_total_points.
    - `result` string, nullable: Which side won: 'Home_Win' or 'Away_Win'.

## 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/026afdfa7802?raw)