API Reference

Predictions API

Session previews with real model output — the same production models that power the Analytics feeds, ahead of every scoring session (Qualifying, Sprint Qualifying, Sprint, Race). Every account gets predictions, including Free: the free tier receives a headline view, paid tiers the full object. Practice sessions are not previewed.

Endpoints

GET/v1/preview/upcoming

Preview of the next upcoming scoring session on the calendar. Returns 404 when no scoring session is upcoming or live.

GET/v1/preview/:sessionId

Preview of one scoring session by its session id (from GET /v1/events). Returns 404 for unknown sessions and400 for sessions that cannot be previewed (e.g. practice).

Both endpoints require authentication — a Bearer token (see Authentication) or a console session cookie. Your subscription tier decides the content depth, not access.

What a preview contains

Field	Type	Description
`session / event / weekend`	`object`	The session, its event, and the full weekend session list (sprint weekends flagged).
`circuit`	`object`	Circuit intelligence: length, turns, laps, pit-loss seconds, overtake index, safety-car rate, degradation profile, downforce level, and a one-line character summary.
`winProbability`	`object`	Per-driver win %, podium %, expected finish, and full finish-position distribution.
`qualifyingProbability`	`object`	Per-driver pole and Q3 probabilities for qualifying-kind sessions.
`qualifyingPace`	`object`	Historical pace reference at this circuit: recent pole time and the Q1/Q2 survival cutoffs.
`strategy`	`object`	Expected stop counts, the first pit window, per-compound tyre model (max laps, deg rate, cliff), and undercut strength.
`grid / practicePace`	`object`	Confirmed or projected grid, and practice long-run pace ranking once sessions have run.
`form`	`object`	Championship form: driver and constructor standings plus title-fight math (lead margin, rounds remaining, decided flag).
`fieldShape`	`object`	Realistic pole contenders, the projected pole→P2 gap, and where the field's pace breaks.
`weather`	`object`	Session weather outlook, when a forecast is available.
`viewerTier / view`	`string`	Your resolved tier and the served depth: "light" (free) or "full" (Live and above).

Free vs. paid depth

The free light view keeps the headlines and trims the depth: win probability, qualifying probability, field-shape contenders, and the grid are cut to the top 3; finish-position distributions are emptied; the per-compound tyre model, constructor pace, and practice pace are null. The full view (Live tier and above) returns everything.

bash

curl "https://api.racehooks.io/v1/preview/upcoming" \
  -H "Authorization: Bearer ${TOKEN}"

# Trimmed response (free tier — view: "light")
{
  "data": {
    "session": { "sessionId": "2026-great-britain_Race", "name": "Race", "startDate": "2026-07-05T14:00:00Z", "status": "upcoming" },
    "event":   { "eventId": "2026-great-britain", "name": "British Grand Prix", "circuitId": "silverstone" },
    "sessionKind": "race",
    "viewerTier": "free",
    "view": "light",
    "circuit": {
      "circuitId": "silverstone",
      "name": "Silverstone Circuit",
      "lengthKm": 5.891,
      "turns": 18,
      "laps": 52,
      "overtakeIndex": 0.62,
      "safetyCarRate": 0.45,
      "downforce": "medium",
      "character": "Fast, flowing layout where straight-line efficiency and high-speed balance decide the order."
    },
    "winProbability": {
      "confidence": 0.78,
      "drivers": [
        { "driverId": "verstappen-max", "winPct": 34.2, "podiumPct": 71.5, "expectedFinish": 2.1, "positionDistribution": [] },
        { "driverId": "norris-lando",   "winPct": 28.7, "podiumPct": 66.9, "expectedFinish": 2.4, "positionDistribution": [] },
        { "driverId": "piastri-oscar",  "winPct": 14.1, "podiumPct": 51.2, "expectedFinish": 3.6, "positionDistribution": [] }
      ]
    },
    "qualifyingPace": { "poleRefMs": 86541, "q1CutoffMs": 88102, "q2CutoffMs": 87464, "sampleRaces": 4 },
    "strategy": {
      "modalStops": 2,
      "expectedStops": { "one": 0.22, "two": 0.64, "threePlus": 0.14 },
      "pitWindow": { "stop": 1, "startLap": 14, "endLap": 22 },
      "compounds": null,
      "undercutStrength": "medium",
      "note": "Two-stop favoured; track position recoverable here."
    },
    "form": { "drivers": ["…top championship standings…"], "constructors": ["…"], "title": { "leaderId": "…", "leadMargin": 12, "decided": false } },
    "fieldShape": { "contenders": [{ "driverId": "verstappen-max", "polePct": 41.0 }], "note": "…" },
    "constructorPace": null,
    "practicePace": null
  }
}

ℹ

Predictions refresh as the weekend progresses — after practice the grid projection and practice pace appear, and after qualifying the confirmed grid replaces the projection. Model documentation lives in the Models reference.