Backtesting
Every price move is timestamped — opens, in-play changes, closes, and reopens — so this history doubles as a backtest-ready dataset: pull a market’s timeline for any event inside your plan’s odds-history window (Starter and above) and replay exactly how it moved.
Opening and closing lines are included on Pro and above (see Opening Lines and Closing Lines below).
Every paid plan can backtest with this history and build or validate its own models, and keep what it pulls while subscribed. Reselling or sharing the data, or using it to train a large language model or general-purpose AI system, is not included: email [email protected] to talk through those. If you cancel, delete the data you’ve stored. See Licensing & Attribution.
Endpoints Overview
The API base URL is
https://therundown.io/api/v2; include /api exactly once. Authenticate with the X-TheRundown-Key header.
Full Market History
GET /api/v2/events/{eventID}/markets/history returns recorded price changes for the requested markets and sportsbooks. Each market is read on its own, so you can request every sportsbook at once.
affiliate_idsis optional. Pass any number of sportsbook ids, or omit it to get every sportsbook your plan includes. Ids your plan does not include are left out.limitapplies to each market. Every requested market returns up tolimitof its newest rows (default 1000, maximum 5000), merged newest first. One response carries at most 15,000 rows, so with more than 3 markets each market’s limit is 15,000 divided by the number of markets (for example 1,250 each for 12 markets).main_line=truestill needs 1 to 3 sportsbook ids, and itslimitcaps the whole response rather than each market. Omittingaffiliate_ids, a blank value,0, or a non-numeric id returns HTTP 400:affiliate_ids is required with main_line=true; pass 1 to 3 sportsbook ids. More than 3 distinct ids returns HTTP 400:with main_line=true, affiliate_ids accepts at most 3 sportsbook ids per request. These requests are rejected before any history read.affiliate_ids=0is not a scores-only sentinel on this route.
market_ids is omitted, the endpoint uses the default markets 1,2,3; pass up to 12 market IDs when selecting markets explicitly.
market_ids is matched literally on this endpoint. Unlike the events endpoints and WebSocket subscriptions, 1,2,3 does not automatically add the in-play markets. To get in-play history, request 41,42,43,96 (live moneyline, spread, total, and team total) explicitly, for example market_ids=1,2,3,41,42,43,96.
Chart history (GET /api/v2/events/{eventID}/markets/{marketID}/history), opening lines, and closing lines also treat affiliate_ids as an optional filter and are not capped at 3 sportsbook ids. Chart history has its own read limit when participant_id, line, or main_line is set; see Single Market History.
Query Parameters
from and to are inclusive filters. Results are returned newest first and each market is capped by limit; invalid or out-of-range limits fall back to 1000. The response does not provide a cursor or has_more flag. If a market reaches its cap, narrow the markets, sportsbooks, or time window before treating it as complete.
Historical responses are subject to the history window included with your plan.
Example Response
The API returnshistory newest first.
market_line_price_id identifies one sportsbook’s price on one line value, so the rows for -3.5 and the row for -4 are two different lines, not one line changing value. The main line moving from -3.5 to -4 shows up as the is_main_line flag leaving -3.5 and arriving on -4 at the same timestamp. A row with change_type: "main_line" means only the flag changed; when odds and the flag change together, the row is a normal price row that carries the new flag.
Tracking Main-Line Moves
Passmain_line=true to keep only rows that were the main line when they were written. Sorted by updated_at, each change of line for a participant is a main-line move (a spread going from -3.5 to -4.5, or a total from 224.5 to 225.5) with its timestamp. Alternate-line rows are excluded.
main_line=true, every row still carries is_main_line, so the same logic works client-side. For real-time tracking, the delta feed and the WebSocket include is_main_line on every update: a main-line move arrives as is_main_line: true on the new line value and is_main_line: false on the old one.
Single Market History (Chart Data)
For building a line movement chart, fetch history for a specific market. This returns a chart-optimized response withseries grouped by sportsbook (keyed by affiliate ID), where each data point uses shorthand fields: t (timestamp), p (price as a string), l (line value), m (main-line flag), and c (closed_at). Chart points are ordered oldest first. A market can contain multiple participants and line values. Pass participant_id to isolate one selection; optionally pass line to isolate one line value, or main_line=true to keep main-line points.
Use participant_id to keep different sides out of the same chart. line is optional; use main_line=true instead when the chart should follow a changing main line. The c field is omitted when the point has no closing timestamp. affiliate_ids is optional on this chart route and is not limited to 3 sportsbooks.
With participant_id, line, or main_line=true, the chart reads recorded prices oldest first until limit points match. If it has read 40,000 recorded prices and limit is still not filled, it returns HTTP 400: chart history for this request would read more than 40000 history rows to apply participant_id, line, or main_line; pass fewer affiliate_ids or a tighter from/to window. This happens when the filter keeps only a small share of a busy market’s history across many sportsbooks. Pass fewer affiliate_ids, or set from and to to a shorter window. A request that fills limit sooner is not affected.
abc123 and 123 in the examples are placeholders. Replace abc123 with an event_id from the events endpoints, and 123 with the public participant_id from participant discovery for the same event and market. The examples pin line=-3.5 so each chart tracks one handicap. If the response reaches limit, narrow the filters or time window; the chart response has no pagination cursor or truncation flag.
Filtering by Time Range
Usefrom and to parameters in RFC 3339 format to scope history to a specific window. This is useful for showing line movement in the last 24 hours or during a specific period.
Opening and Closing Parameters
Both event and sport/date snapshot endpoints accept these filters:
An event can be returned without prices when no recorded price matches the filters. These endpoints require a plan with historical-data access. Opening and closing snapshots also apply the plan’s history window to the event date; requests outside that window return
403. Omit hide_closed or set it to false when retrieving completed-event snapshots so currently closed prices remain included.
Opening Lines
The openers endpoints return the first recorded price for each available market line and sportsbook. They can return data before, during, or after an event when a price has been recorded. The response uses the same V2 events structure (withmarkets, participants, lines, and prices).
Closing Lines
The closing endpoint returns the latest recorded price at or before the event’s scheduled start time. Before the event starts, that value is provisional and may change; after the start, it represents the pre-start closing snapshot. The response uses the same V2 events structure as openers. See the event closing reference and sport/date closing reference.11,12 and sportsbooks 19,23. Replace the event ID with an event inside your plan’s history window:
hide_closed can remove prices from a completed event when those prices are closed; the event and its score can still be returned.
Building a Line Movement Chart
Here is a complete example that fetches one participant’s spread history and formats the data for a charting library. The chart endpoint returnsseries as a map keyed by affiliate ID, with each entry containing an affiliate_name and data array of {t, p, l, m, c} points.
Comparing Openers to Current Lines
A common use case is showing how far a line has moved from its opener. Fetch both the opener and current odds, then compute the difference. Both endpoints return the same V2 events structure withmarkets > participants > lines > prices.
Both requests use main_line=true to compare each participant’s main spread in the opening and current snapshots. Keep the signed line value in the output: the main spread can move between snapshots.
Next Steps
Getting Live Odds
Fetch current odds for today’s games
Player Props
Historical data for prop markets too
Market IDs
Full list of market types
Sportsbook IDs
All tracked sportsbooks