Developer buying guide
Query timestamped pre-match prices for one event and selection, then group the returned series by bookmaker for charts, audits and leakage-safe backtests.
curl --request GET \
--header "X-API-Key: $ODDS_API_KEY" \
"https://api.odds-api.net/v1/events/{event_id}/odds/history?selection_key={selection_key}&from_ts=2026-09-01T00:00:00Z&to_ts=2026-09-02T00:00:00Z"{
"event_id": "nba-example-001",
"selection_key": "moneyline:home",
"price_type": "decimal",
"series": [{
"bookmaker": "pinnacle",
"points": [
{"tick_ts": "2026-09-01T08:00:00Z", "is_available": true, "odds": 1.91},
{"tick_ts": "2026-09-01T08:14:20Z", "is_available": true, "odds": 1.95}
]
}],
"meta": {"from_ts": "2026-09-01T00:00:00Z", "to_ts": "2026-09-02T00:00:00Z"}
}Decision evidence
History is an event-and-selection query product, not a bulk archive download.
| Requirement | odds-api.net contract |
|---|---|
| Endpoint | GET /v1/events/{event_id}/odds/history |
| Time window | Bounded ISO8601 UTC from_ts and to_ts parameters. |
| Selection | Use the stable selection_key returned by the event odds snapshot. |
| Filters | Narrow by bookmaker, market group, price type and point limit where supported. |
| Continuity | SSE and WebSocket history streams are available for supported line-movement consumers. |
| Access | A paid base plan plus an enabled History Lite or History Pro add-on. |
| Lookback | 30 days with History Lite or 365 days with History Pro, where retained. |
| History credits | One history credit, plus one per 1,000 returned points, plus payload-size units per MB. |
| Timestamp meaning | tick_ts is the recorded price-point time. The series is event driven, so do not assume fixed-interval samples. |
Historical records describe retained pre-match prices. They are not a live-price fallback, form database or guaranteed complete archive for every bookmaker and market.
Implementation guidance
Keep the event, selection and timestamp boundaries explicit from the first query.
Start from a current or retained event ID, then query one stable selection through a bounded time window.
Use only information that would have existed at each decision time.
Define the close before calculating a closing-line metric.
Recommended entry point
Builder is $90/month. History Lite adds $50/month for a 30-day retained lookback, making the starting historical setup $140/month.
Poor fit
The history API is deliberately narrower than a bulk sports-data warehouse.
Verification
These product facts come from the current odds-api.net documentation, pricing contract and data licence.
Product contract verified 12 September 2026 against the public API schema and pricing system.
Short answers
Access, lookback, backtesting and data-boundary answers.
History Lite provides up to 30 retained days. History Pro provides up to 365 retained days. The phrase where retained matters: the endpoint is not a guarantee that every event, bookmaker, market and selection exists for the full window.
No. Historical access requires an eligible paid base plan and a separately enabled history add-on. The recommended starting setup is Builder plus History Lite.
Yes. Use bounded UTC windows and a stable selection_key, and prevent prices recorded after the model's decision time from entering the test.
No. odds-api.net currently provides retained pre-match sportsbook price history, not in-play sportsbook odds history.
Yes. Supported history consumers can use SSE or the matching WebSocket route. Begin with a snapshot and reconnect from the latest continuation point.
No. Query history by event, selection and bounded time window. Contact support if a research project requires a different export shape or retention agreement.