API reference

List events

Upcoming, in-play and finished events, filtered by sport, league, country, dates or status.

GET/odds/v1/events

Cost: 1 token
Authentication: X-API-Key, demo key works

Parameters

sportstringoptional
A sport key from /sports, e.g. soccer, basketball.
leaguestringoptional
A league key from /sports, e.g. epl, nba.
countrystringoptional
A country code, e.g. au, gb.
dateYYYY-MM-DDoptional
One event day (the date in the event_id). Same as since and until set to that day.
sinceYYYY-MM-DDoptional
First event day, inclusive. A filter like sport and league: events come back in start-time order, live and finished in one list. At most 31 days from until (400 if more). One given alone: until defaults to tomorrow, since to 6 days before until.
untilYYYY-MM-DDoptional
Last event day, inclusive. Use date or since/until, not both.
statusstringoptional
prematch, in_play or finished. finished with no window = the last 7 days.
include_outrightsbooleanoptional
Include futures and tournament markets.Default: false
limitintegeroptional
1 to 500 per page (at most 200 of them finished).Default: 100
cursorstringoptional
next_cursor from the previous page, with the same filters. Pass it back until it is null.

Request

curl -s "https://api.b337.ai/odds/v1/events?league=epl&limit=1" \
  -H "X-API-Key: demo"

import requests

resp = requests.get(
    "https://api.b337.ai/odds/v1/events",
    params={"league": "epl", "limit": "1"},
    headers={"X-API-Key": "demo"},
    timeout=10,
)
resp.raise_for_status()
print(resp.json())

// Node 18+, saved as an .mjs file
const res = await fetch("https://api.b337.ai/odds/v1/events?league=epl&limit=1", {
  headers: { "X-API-Key": "demo" },
});
console.log(await res.json());

Response

200 OK

{
  "count": 1,
  "truncated": true,
  "data": [{
    "event_id": "soccer/gb/epl/arsenal_fc_v_leeds_united_fc/2026-10-10",
    "sport": "soccer",
    "league": "epl",
    "country": "gb",
    "name": "Arsenal FC v Leeds United FC",
    "home": "Arsenal FC",
    "away": "Leeds United FC",
    "participants": ["Arsenal FC", "Leeds United FC"],
    "competitors": [
      {"id": "soccer:arsenal_fc", "name": "Arsenal FC", "side": "home",
       "logo_url": "https://api.b337.ai/odds/v1/media/logo/2f6693605fb6dcfa.png"},
      {"id": "soccer:leeds_united_fc", "name": "Leeds United FC", "side": "away",
       "logo_url": "https://api.b337.ai/odds/v1/media/logo/c6d81a00ff2a0516.png"}],
    "is_outright": false,
    "start_time": "2026-10-10T11:30:00Z",
    "status": "prematch",
    "books": ["bet365", "betfair", "pinnacle", "sportsbet", "tab"]
  }],
  "generated_at": "2026-10-05T03:06:34Z"
}

// A finished event (GET /events?league=mlb&date=2026-09-26), trimmed:
{
  "count": 18, "truncated": false, "next_cursor": null,
  "since": "2026-09-26", "until": "2026-09-26",
  "data": [{
    "event_id": "baseball/us/mlb/philadelphia_phillies_v_tampa_bay_rays/2026-09-26",
    "sport": "baseball", "league": "mlb", "country": "us",
    "name": "Philadelphia Phillies v Tampa Bay Rays",
    "start_time": "2026-09-26T23:15:00Z", "status": "finished",
    "books": ["bet365", "betfair", "fanduel", "pinnacle", "sportsbet", "tab"],
    "has_closing": true, "off_at": "2026-09-26T23:15:00Z", "off_source": "scheduled"
  }]
}

Fields

event_id is opaque: store it and send it back verbatim, never build one. See event_id.
competitors: each side of the event, with its id (the team_id that /teams lists), name, side (home or away) and logo_url (a crest, or a flag for an international side; null where we hold none). participants stays the plain list of names. Empty for an outright. See team_id and player_id.
status: prematch, in_play or finished. See statuses.
score (Business and Enterprise): on a row in play or finished, the event's score as on /scores: status (scheduled, live or final), home_score, away_score, source and source_game_id. It is null on a prematch row and for any league outside the covered list. No extra tokens.
since and until (or one date) are filters like sport and league: add them to any query. You get one list ordered by start time, live and finished events together, so a window can be wholly in the past, wholly ahead or span both. At most 31 days between them (longer is a 400; page it in slices). Without them you get what is listed now. Finished events go back to 2026-08-26.
Examples: sport=basketball&league=nba&since=2026-09-05&until=2026-10-05 is NBA games over the last 30 days; since=2026-10-10&until=2026-10-11 is this weekend's fixtures.
On a finished row, has_closing says whether /odds has closing prices for it (null = could not be checked just now). off_at is when it went off; off_source is how we know: quorum (two or more books said so), single_witness (one did) or scheduled (none did; the listed start).
Paging: pass next_cursor back as cursor, with the same filters, until it is null. A page can hold fewer than limit rows and still not be the last.
books: which books currently list this event (we hold a card for it read within the last hour). On a finished row, the books that were bound to it.
truncated: true means more events matched than limit; narrow the query.
For an outright, home and away are null and participants is empty.

Parameters

sportstringoptional
A sport key from /sports, e.g. soccer, basketball.
leaguestringoptional
A league key from /sports, e.g. epl, nba.
countrystringoptional
A country code, e.g. au, gb.
dateYYYY-MM-DDoptional
One event day (the date in the event_id). Same as since and until set to that day.
sinceYYYY-MM-DDoptional
First event day, inclusive. A filter like sport and league: events come back in start-time order, live and finished in one list. At most 31 days from until (400 if more). One given alone: until defaults to tomorrow, since to 6 days before until.
untilYYYY-MM-DDoptional
Last event day, inclusive. Use date or since/until, not both.
statusstringoptional
prematch, in_play or finished. finished with no window = the last 7 days.
include_outrightsbooleanoptional
Include futures and tournament markets.Default: false
limitintegeroptional
1 to 500 per page (at most 200 of them finished).Default: 100
cursorstringoptional
next_cursor from the previous page, with the same filters. Pass it back until it is null.

Request

curl -s "https://api.b337.ai/odds/v1/events?league=epl&limit=1" \
  -H "X-API-Key: demo"

import requests

resp = requests.get(
    "https://api.b337.ai/odds/v1/events",
    params={"league": "epl", "limit": "1"},
    headers={"X-API-Key": "demo"},
    timeout=10,
)
resp.raise_for_status()
print(resp.json())

// Node 18+, saved as an .mjs file
const res = await fetch("https://api.b337.ai/odds/v1/events?league=epl&limit=1", {
  headers: { "X-API-Key": "demo" },
});
console.log(await res.json());

Response

200 OK

{
  "count": 1,
  "truncated": true,
  "data": [{
    "event_id": "soccer/gb/epl/arsenal_fc_v_leeds_united_fc/2026-10-10",
    "sport": "soccer",
    "league": "epl",
    "country": "gb",
    "name": "Arsenal FC v Leeds United FC",
    "home": "Arsenal FC",
    "away": "Leeds United FC",
    "participants": ["Arsenal FC", "Leeds United FC"],
    "competitors": [
      {"id": "soccer:arsenal_fc", "name": "Arsenal FC", "side": "home",
       "logo_url": "https://api.b337.ai/odds/v1/media/logo/2f6693605fb6dcfa.png"},
      {"id": "soccer:leeds_united_fc", "name": "Leeds United FC", "side": "away",
       "logo_url": "https://api.b337.ai/odds/v1/media/logo/c6d81a00ff2a0516.png"}],
    "is_outright": false,
    "start_time": "2026-10-10T11:30:00Z",
    "status": "prematch",
    "books": ["bet365", "betfair", "pinnacle", "sportsbet", "tab"]
  }],
  "generated_at": "2026-10-05T03:06:34Z"
}

// A finished event (GET /events?league=mlb&date=2026-09-26), trimmed:
{
  "count": 18, "truncated": false, "next_cursor": null,
  "since": "2026-09-26", "until": "2026-09-26",
  "data": [{
    "event_id": "baseball/us/mlb/philadelphia_phillies_v_tampa_bay_rays/2026-09-26",
    "sport": "baseball", "league": "mlb", "country": "us",
    "name": "Philadelphia Phillies v Tampa Bay Rays",
    "start_time": "2026-09-26T23:15:00Z", "status": "finished",
    "books": ["bet365", "betfair", "fanduel", "pinnacle", "sportsbet", "tab"],
    "has_closing": true, "off_at": "2026-09-26T23:15:00Z", "off_source": "scheduled"
  }]
}

Fields

event_id is opaque: store it and send it back verbatim, never build one. See event_id.

competitors: each side of the event, with its id (the team_id that /teams lists), name, side (home or away) and logo_url (a crest, or a flag for an international side; null where we hold none). participants stays the plain list of names. Empty for an outright. See team_id and player_id.

status: prematch, in_play or finished. See statuses.

score (Business and Enterprise): on a row in play or finished, the event's score as on /scores: status (scheduled, live or final), home_score, away_score, source and source_game_id. It is null on a prematch row and for any league outside the covered list. No extra tokens.

since and until (or one date) are filters like sport and league: add them to any query. You get one list ordered by start time, live and finished events together, so a window can be wholly in the past, wholly ahead or span both. At most 31 days between them (longer is a 400; page it in slices). Without them you get what is listed now. Finished events go back to 2026-08-26.

Examples: sport=basketball&league=nba&since=2026-09-05&until=2026-10-05 is NBA games over the last 30 days; since=2026-10-10&until=2026-10-11 is this weekend's fixtures.

On a finished row, has_closing says whether /odds has closing prices for it (null = could not be checked just now). off_at is when it went off; off_source is how we know: quorum (two or more books said so), single_witness (one did) or scheduled (none did; the listed start).

Paging: pass next_cursor back as cursor, with the same filters, until it is null. A page can hold fewer than limit rows and still not be the last.

books: which books currently list this event (we hold a card for it read within the last hour). On a finished row, the books that were bound to it.

truncated: true means more events matched than limit; narrow the query.

For an outright, home and away are null and participants is empty.