---
title: "List forecasted wagers (player props; main-line rows ship sport-by-sport)"
method: GET
path: "/v1/intelligence/forecasts"
tags: ["events"]
---

# List forecasted wagers (player props; main-line rows ship sport-by-sport)

`GET /v1/intelligence/forecasts`

## Request

- Base URL: `https://lumify.ai`
- URL: `https://lumify.ai/v1/intelligence/forecasts`
- Auth: HTTP bearer

## Query parameters

- `sport` string, required: Sport slug. Prop-forecast sports: mlb, ncaaf, nfl, nba, ncaab, nhl. Main-line forecast sports: tennis, nfl, ncaaf, mlb, soccer (high-confidence moneyline, spread, and total).
- `date` string, nullable: UTC slate date YYYY-MM-DD. Defaults to today UTC.
- `market` 'h2h' | 'spreads' | 'totals', nullable: Main-line family filter (h2h, spreads, or totals). Main-line sports publish a high-confidence side of each family when the lean clears the coin-flip gate. Ignored on prop-only sports (nba, ncaab, nhl).
- `limit` integer: Max wagers to return (1–100). Default 25.

## Response `200`

Daily board of forecasted wagers from our model — player props (MLB, NCAAF, NFL, NBA, NCAAB, NHL) and high-confidence main-line picks on tennis, NFL, NCAAF, MLB, and soccer (moneyline, spread, total — one side per market when the uncertainty band does not include a coin flip). Tennis moneyline is ranking Bradley-Terry; tennis spreads/totals are a Normal-approx games model. Other sports use the published assessment probability. Each wager has p_hit (model probability the picked outcome hits), conviction (board rank), and posted books prices. Prop rows: player, market, line, side. Main-line rows: bet_type, player_role, market=h2h|spreads|totals. reliability is emerging on v0. Empty slate is still 200, still 1 credit. Same objects also appear per-event on GET /v1/events/{id}/intelligence as forecasts[]. A high-confidence main-line row's research.note is copied to the matching bets[].narrative. Not an EV / claim-ladder surface — see GET /v1/intelligence/ev for gated main-line +EV. Field catalog: https://lumify.ai/docs/reference#intelligence-forecasts

- ForecastsResponse
  - `sport` string, required: Sport slug this slate was scored for.
  - `date` string, required: UTC slate date (YYYY-MM-DD).
  - `model_version` string, required: Scorer version used for every wager on this page.
  - `reliability` string, required: Default badge on this slate. v0 ships `emerging`; each wager repeats the same field. Cells promote as a scored history accumulates.
  - `wagers` ForecastWager[]: Selected forecasted wagers, highest `conviction` first. Empty is still 200 and still 1 credit — nothing on the slate for this sport/date.
    - `event_id` integer, nullable: Lumify event ID. Present on the daily slate (`GET /v1/intelligence/forecasts`); omitted on `GET /v1/events/{id}/intelligence` `forecasts[]` (the event is the path).
    - `sport` string, nullable: Sport slug. Slate only.
    - `league` string, nullable: League slug, if any. Slate only.
    - `commence_time` string, nullable: ISO-8601 UTC scheduled start. Slate only.
    - `home_team` string, nullable: Home team display name. Slate only.
    - `away_team` string, nullable: Away team display name. Slate only.
    - `player` string, nullable: Player display name from the priced line. Null on main-line rows with no player attribution (`bet_type` is a match-level token like OVER/UNDER/ML_DRAW).
    - `player_id` integer, nullable: Lumify player ID. Bound by exact / Jr-stripped name match to the priced line. Null on main-line rows with no player attribution.
    - `bet_type` string, nullable: Main-line token when this row is a main-line forecast — `ML_P1`/`ML_P2`/`ML_HOME`/`ML_AWAY`/`ML_DRAW`, `SPREAD_P1`/`SPREAD_P2`/`SPREAD_HOME`/`SPREAD_AWAY`, or `OVER`/`UNDER` (same vocabulary as `bets[].bet_type` and `list_ev`). Null on player-prop rows — that's the discriminator between the two row shapes. Tennis sets `ML_P1`/`ML_P2` (moneyline, ranking Bradley-Terry), `SPREAD_P1`/`SPREAD_P2` (game handicap), and `OVER`/`UNDER` (total games — soft-book game-unit lines only, never Pinnacle's set-unit total). NFL / NCAAF / MLB / soccer set the same tokens from a high-confidence assessment lean (one side per market; coin flips are not emitted as picks).
    - `player_role` string, nullable: `home`/`away` for team sports or `p1`/`p2` for head-to-head sports, set only alongside a non-null `bet_type`. Null for player-prop rows and for match-level main-line tokens (OVER, UNDER, ML_DRAW).
    - `market` string, required: Player-prop rows: prop category — counting stats. MLB: strikeouts_pitcher, hits, rbis, runs, strikeouts_batter, hits_allowed, earned_runs, outs_recorded. NFL/NCAAF: passing_yards, rushing_yards, receiving_yards, receptions, passing_tds, rushing_tds, touchdowns (anytime-TD combo: rushing + receiving + defensive TDs), rush_rec_yards, pass_rush_yards. NBA/NCAAB: points, rebounds, assists, steals, blocks, threes_made. NHL: goals, hockey_assists, shots_on_goal. Main-line rows (when `bet_type` is set): the main-line family — `h2h`, `spreads`, or `totals`.
    - `line` number, nullable: Posted line the model was scored against. Player-prop and `totals` main-line rows: Over/Under number. `spreads` main-line rows: the spread number. Null on `h2h`/moneyline rows.
    - `side` string, nullable: Player-prop rows: `over` or `under` — the more likely side given the player's shrunken rate versus `line`. The model always picks one when the line is in range. Null on main-line rows — read the picked outcome from `bet_type` instead.
    - `p_hit` number, required: Model probability (0–1) that the picked outcome (`side` on prop rows, `bet_type` on main-line rows) hits. Prop rows: built from the player's shrunken counting-stat rate (Poisson vs the posted Over/Under). Optional `research` may nudge a prop's `p_hit` by at most ±0.03; the chosen side stays the same.
    - `interval` number[], required: `[lo, hi]` stated band around `p_hit`. Wider when `sufficiency` is low (thin recent sample). A stated evidence band, not a statistical confidence interval.
    - `sufficiency` number, required: Evidence weight on 0–1: n / (n + 12), where n is the recent-form game count (typically L10). A player with 10 recent games has sufficiency ≈ 0.45 — about half the rate is player-observed, half prior. The wager still ships at any sufficiency; this field tells you how much of `p_hit` is earned from this player's own boxes.
    - `reliability` string, required: Badge on this sport×market cell: `emerging`, `moderate`, `high`, or `informational`. v0 ships `emerging` for every wager; cells promote as a scored history accumulates.
    - `conviction` number, required: Board rank key on 0–1: |p_hit − 0.5| × 2 × sufficiency × research multiplier. A 0.76 call on a thin sample ranks below a 0.62 call on a long one. Highest conviction first on the daily slate.
    - `model_version` string, required: Scorer version, e.g. `forecast-v0`.
    - `selected` boolean, required: True when this wager is on the daily board (top conviction, up to 3 per event / 25 on the slate). On `GET /intelligence` the array includes both selected rows and the rest of the event catalog.
    - `books` object, required: American price for the picked outcome, keyed by bookmaker slug (e.g. `{draftkings: -453}`). Posted market price for the side/bet_type the model picked — use it to see what books are charging for that outcome.
    - `drivers` ForecastDriver[]: Signed contributions that moved `p_hit`. Read `input` as the measured rate/rating behind the pick and `effect` as how far it lifts (or lowers) the chosen outcome versus a baseline on the same line.
      - `id` string, required: Namespaced driver id. Player-prop rows: typically `player.l10_rate` — the recent-form counting-stat rate that fed the Poisson step (also `player.season_rate` when L10 is too thin). Main-line rows would use a different namespace (e.g. a rating or surface split) once a main-line forecast model ships.
      - `input` number, nullable: Measured rate/rating behind this driver, in the units native to the underlying model (e.g. 0.27 runs/game, 7.4 strikeouts/start for the prop rate model). This is λ before the Poisson vs the posted line on prop rows.
      - `effect` number, required: Signed shift in `p_hit` versus a baseline case on the same line, in probability units. Positive / `direction=up` means this driver lifts the chosen outcome. 0.0 on yardage markets (league means are diluted by backups).
      - `direction` string, required: `up` when `effect` > 0, `down` when `effect` < 0, `neutral` at zero.
    - `research` object, nullable: Optional Deep Research overlay when the background job has written a row for this wager — every wager on the daily board (`selected: true`), plus other high-probability wagers (`p_hit` ≥ 0.80) in the catalog: `{stance, conviction, note}`. `stance` is `validate` / `neutral` / `invalidate`. `note` is the wager-level why (the fact the model cannot see) — on a selected main-line row it is also copied to `bets[].narrative`. Validate / invalidate rows always carry a note. Validate nudges `p_hit` up by at most 0.03 and lifts conviction. Invalidate drops the wager from `forecasts[]` and the daily board — it is not a recommended pick. The chosen `side` stays the same. Null means read `p_hit` from the rate model alone — missing research is fail-open, not a 400.
  - `total` integer, required: Count of `wagers` on this page.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api.md) · [All operations](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api/revisions/f91ea41a2606?raw)