Historical Odds

What are closing lines?

The closing line is the final price a bookmaker offered before an event started. It is the most informative number a bookmaker publishes, because it reflects every bet taken and every adjustment made right up to kick-off. Most quantitative work starts here: you compare your model’s price, or the price you actually got, against the close. Odds-API.io stores closing odds for settled events across every bookmaker and market we cover.

Which endpoint should I use?

There are two ways to get closing lines, and picking the right one matters.

Endpoint	Use it when	Plans
`/v3/historical/closing-lines`	You want closing odds for many events at once, such as a whole league or season	Paid
`/v3/historical/events`	You only need the fixture list and results for a league and date range	Free and paid
`/v3/historical/odds`	You already have an event ID and want everything for that one event	Free and paid

If you are building a dataset, use /v3/historical/closing-lines. Pulling a season through the per-event endpoint means one request per match, which for five leagues over a season is roughly 1,900 requests. The same data comes back from the bulk endpoint in about 20.

Fetching closing lines in bulk

/v3/historical/closing-lines takes a sport, up to 10 leagues, a date range and the markets you care about, and returns every settled event in that window with its closing odds attached.

Query Parameters

Parameter	Required	Description
`apiKey`	Yes	Your API key
`sport`	Yes	Sport slug (e.g. `football`)
`leagues`	Yes	Comma-separated league slugs, maximum 10 (e.g. `england-premier-league,spain-la-liga`)
`from`	Yes	Start date in RFC3339 format (e.g. `2026-01-01T00:00:00Z`)
`to`	Yes	End date in RFC3339 format. Maximum 366 days after `from`
`markets`	Yes	Comma-separated market names (e.g. `ML,Totals`)
`bookmakers`	Yes	Comma-separated bookmaker names, maximum 30
`limit`	No	Events per response. Capped at 100; use `limit` and `skip` to paginate
`skip`	No	Number of events to skip

markets and bookmakers are both required here. A single call can otherwise cover 100 events across 30 bookmakers and every market, which produces a response nobody wants to download.

Example

curl "https://api.odds-api.io/v3/historical/closing-lines?apiKey=YOUR_API_KEY&sport=football&leagues=england-premier-league,spain-la-liga&from=2026-01-01T00:00:00Z&to=2026-01-31T23:59:59Z&markets=ML&bookmakers=Bet365,Unibet&limit=100"

The response is an array of events, each with the same shape returned by /v3/historical/odds:

[
  {
    "id": 123456,
    "home": "Arsenal",
    "away": "Chelsea",
    "date": "2026-01-14T20:00:00Z",
    "status": "settled",
    "sport": { "name": "Football", "slug": "football" },
    "league": { "name": "England - Premier League", "slug": "england-premier-league" },
    "scores": { "home": 2, "away": 1, "periods": [] },
    "bookmakers": {
      "Bet365": [
        {
          "name": "ML",
          "updatedAt": "2026-01-14T19:58:12Z",
          "odds": [{ "home": "2.10", "draw": "3.40", "away": "3.60" }]
        }
      ]
    }
  }
]

Events with no odds from your selected bookmakers still appear, with an empty bookmakers object. That is deliberate: you can tell the difference between a match we have no prices for and a match that never happened.

Paginating a full season

The span limit is 366 days, so a whole season fits in one date range. Page through it with skip:

import requests

BASE = "https://api.odds-api.io/v3/historical/closing-lines"
params = {
    "apiKey": "YOUR_API_KEY",
    "sport": "football",
    "leagues": "england-premier-league",
    "markets": "ML",
    "bookmakers": "Bet365,Unibet",
    "limit": 100,
}

def fetch_season(start, end):
    events, skip = [], 0
    while True:
        page = requests.get(BASE, params={**params, "from": start, "to": end, "skip": skip}).json()
        events.extend(page)
        if len(page) < params["limit"]:
            return events
        skip += params["limit"]

season = fetch_season("2026-03-01T00:00:00Z", "2026-12-01T00:00:00Z")
print(f"{len(season)} events")

A short page means you have reached the end. A 240-match season is three requests at limit=100.

Fetching a single event

If you already have an event ID, /v3/historical/odds returns the closing odds for that one event.

Query Parameters

Parameter	Required	Description
`apiKey`	Yes	Your API key
`eventId`	Yes	Event ID from `/v3/historical/events`
`bookmakers`	Yes	Comma-separated bookmaker names, maximum 30
`markets`	No	Comma-separated market names. Returns all markets when omitted

curl "https://api.odds-api.io/v3/historical/odds?apiKey=YOUR_API_KEY&eventId=123456&bookmakers=Bet365&markets=ML"

Adding markets is worth doing even when you do not strictly need it. A busy football match carries hundreds of markets per bookmaker, so filtering server-side keeps responses small.

Finding events

/v3/historical/events returns settled events for one league and date range, with final scores. Use it when you want results and fixtures rather than odds.

Query Parameters

Parameter	Required	Description
`apiKey`	Yes	Your API key
`sport`	Yes	Sport slug (e.g. `football`)
`league`	Yes	A single league slug
`from`	Yes	Start date in RFC3339 format
`to`	Yes	End date in RFC3339 format. Maximum 31 days after `from`

curl "https://api.odds-api.io/v3/historical/events?apiKey=YOUR_API_KEY&sport=football&league=england-premier-league&from=2026-01-01T00:00:00Z&to=2026-01-31T23:59:59Z"

Limits

Limit	Value	Applies to
Date span	366 days per request	`/v3/historical/closing-lines`
Date span	31 days per request	`/v3/historical/events`
Leagues	10 per request	`/v3/historical/closing-lines`
Bookmakers	30 per request	`/v3/historical/closing-lines`, `/v3/historical/odds`
Events	100 per response	`/v3/historical/closing-lines`
Events	1000 per response	`/v3/historical/events`

Plan access

/v3/historical/events and /v3/historical/odds are available on every plan, including the free one, so you can evaluate the data before committing. /v3/historical/closing-lines is a paid feature. Free plans calling it get a 403 explaining the alternative. You can upgrade in the dashboard.

Notes on the data

Closing odds go back to December 2025. Events before that are returned by /v3/historical/events with their scores, but carry no odds, so they come back with an empty bookmakers object. Only events with a status of settled are returned. If a match has finished but has not settled in our pipeline yet, it will not appear. The core market names are the same across sports: ML (moneyline / match winner), Totals and Spread, each with half-time variants such as ML HT and Totals HT. Beyond those, availability depends on the sport. Football adds Correct Score, Both Teams To Score, Double Chance, Half Time / Full Time and European Handicap. Basketball adds Player Props and 3-Way Result. Tennis uses Totals (Games) and Spread (Games) alongside per-set markets like ML 1st Set. Matching is case-insensitive, so ml and ML both work, but the name must match in full. There is no market called “Match Winner”, and no bare “Over/Under” or “Asian Handicap”, though longer names such as Goals Over/Under and Alternative Asian Handicap do exist. To see exactly which markets an event carries, call /v3/historical/odds for it without a markets filter.

Getting Started

Guides

Examples

What are closing lines?

Which endpoint should I use?

Fetching closing lines in bulk

Query Parameters

Example

Paginating a full season

Fetching a single event

Query Parameters

Finding events

Query Parameters

Limits

Plan access

Notes on the data

​What are closing lines?

​Which endpoint should I use?

​Fetching closing lines in bulk

​Query Parameters

​Example

​Paginating a full season

​Fetching a single event

​Query Parameters

​Finding events

​Query Parameters

​Limits

​Plan access

​Notes on the data

What are closing lines?

Which endpoint should I use?

Fetching closing lines in bulk

Query Parameters

Example

Paginating a full season

Fetching a single event

Query Parameters

Finding events

Query Parameters

Limits

Plan access

Notes on the data