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. Any name listed by `/v3/bookmakers` works, and the response reports odds under that same name
`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. scores.periods is keyed by period: p1, ft, ot and so on. Cricket instead uses inning1, inning2, and adds cricket-only wickets and overs pairs; see Cricket Scores for the shape.

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. Any name listed by `/v3/bookmakers` works, and the response reports odds under that same name
`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. Events also carry numeric homeId and awayId team ids, matching /v3/participants and the live /v3/events ids. Coverage: roughly 90% of events from March 2026 onward, partial for February 2026, and not available before that. Rows without a resolved id omit the two fields.

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"

Searching events by team

/v3/historical/events/search finds settled events by team name across all leagues, so you don’t need to know which league a match was in. Results come back newest first with final scores, in the same shape as /v3/historical/events.

Query Parameters

Parameter	Required	Description
`apiKey`	Yes	Your API key
`query`	Yes	Team name fragment, minimum 3 characters. Matches home or away, case-insensitive
`sport`	No	Sport slug (e.g. `football`) to narrow the search
`from`	No	Start date in RFC3339 format. Defaults to 31 days before `to`
`to`	No	End date in RFC3339 format. Defaults to now. Maximum 31 days after `from`

curl "https://api.odds-api.io/v3/historical/events/search?apiKey=YOUR_API_KEY&query=Brann&sport=football"

Pair it with /v3/historical/odds to pull closing odds for a match you found by name.

Limits

Limit	Value	Applies to
Date span	366 days per request	`/v3/historical/closing-lines`
Date span	31 days per request	`/v3/historical/events`, `/v3/historical/events/search`
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`
Events	100 per response	`/v3/historical/events/search`

Plan access

/v3/historical/events, /v3/historical/events/search 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, 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. Baseball names its first five innings in full rather than with the HT suffix: First 5 Innings ML, First 5 Innings Spread and First 5 Innings Totals. 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 Corners do exist. Call GET /v3/markets?sport=<sport> for the exact names a sport serves. 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

Searching events by team

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

​Searching events by team

​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

Searching events by team

Query Parameters

Limits

Plan access

Notes on the data