Motorsport Predictions API: Previews and Probabilities
Session previews with real model output from 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
/v1/preview/upcomingPreview of the next upcoming scoring session on the calendar. Returns 404 when no scoring session is upcoming or live.
/v1/preview/:sessionIdPreview 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 % and top-10 % (also served as pointsPct on Free and Developer). Free and Developer values are rounded to 5% and carry no finish-position distribution; higher tiers get exact values and the full distribution. |
raceOutlook | object | Race sessions: safetyCarPct, the chance of at least one safety car or virtual safety car. Rounded to 5% on Free and Developer, exact on higher tiers. |
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. The rain chance (precipProbabilityPct) is rounded to 5% on Free and Developer. |
viewerTier / view | string | Your resolved tier and the served depth: "light" (Free), "grid" (Developer) or "full" (higher tiers). |
Free vs. paid depth
The free light view is win chances only: the top 3 drivers, each with a win probability rounded to the nearest 5% (above 0 and below 5% is served as 5 with a bounds marker of <5%; above 95% and below 100 as 95 with >95%), plus the circuit, schedule, championship form and past results. It is set before practice: from the start of the weekend's first session the response carries frozen: true and frozenAt, and does not change. Podium, points, safety-car, rain, qualifying, strategy and pace are not in the Free view. The Developer grid view returns win, podium and points (top-10) for the whole field, plus safety-car and rain chances, updated after FP3 and after qualifying, rounded to 5% with finish-position distributions emptied. Higher tiers get the full view with exact numbers and the distributions.
Developer Live+ (in-race chances)
Developer Live+ ($498/mo: Developer plus $399) adds the lite.race-odds feed and GET /v1/lap/:sessionId/latest and /history for the current session. Each lap's chances are released one lap behind, when the leader completes the next lap, and the last lap at the chequered flag. Every value is rounded to the nearest 5%. In-race chances may not be used to set, trade or make markets in wagering odds. It also switches live timing from 5-second snapshots to every update, over webhooks or SSE.
Errors
| Field | Type | Description |
|---|---|---|
401 | Unauthorized | Missing, expired or invalid Bearer token (or no console session). |
404 | Not found | /v1/preview/upcoming: no scoring session is upcoming or live. /v1/preview/:sessionId: unknown session id. |
403 | Forbidden | /v1/preview/:sessionId: historical previews are on Custom plans. Free and Developer include the current and next race weekend. |
400 | Bad request | /v1/preview/:sessionId: the session cannot be previewed, for example a practice session. |
429 | Too many requests | Rate limit exceeded; back off and retry. Limits by plan are on the API reference. |