Stable event ids
One id per event, what names an event, which fields stay as first served, ids merged into another, course names and the catch-all sport keys.
One id per event
Every event has one id, opaque and the same on every route: raw, the event route, /, the matched boards and historical odds. It is kept for as long as the event is served, so it is the key to store.
When two ids turn out to be one fixture, the id served first is kept and the other is listed in that event's previous_, on every route that serves it: /, /, / and, since 14 November 2026, the matched boards, where it comes after competition_. previous_ never holds the event's own id.
A merged id still answers on / and in eventIds with the event it became while that event is on the board, and again if its fixture is listed again within 60 days. Once that event has left the board, both ids answer 404 unknown_ on / and return no event in eventIds, and historical odds still serve both. On a raw updatedSince walk, a merge shows in meta.removed with the reason merged and the surviving id in merged_: Paging through raw odds covers it.
What names an event
Since 13 November 2026, every event names itself on every route, in one of three ways:
- A team fixture:
home_andteam away_. Home and away never swap while a bookmaker lists them in that order.team - A race, horse or greyhound:
venue, the course, such asCheltenhamorDoomben (AUS). Itshome_andteam away_areteam nullon raw, the event route and/, and left out on the matched racing boards.v2/ events - Any other event with no two teams, such as a golf tournament, an outright or a special:
event_, such asname The Masters 2027.
Races and outrights
venue and event_ come after the teams (after commence_ on a matched race, which has no team fields), and each appears only on the events it names. An ante-post market carries its festival's course in venue, or none, and its category in event_, such as Ante-Post National Hunt.
On the matched boards that list greyhound races (standard), a race also keeps the event_ it was first served with, its UK off time and course (21:04 Central Park), beside venue. Raw, the event route and / serve a race's venue alone.
To show a race, venue and commence_ name it; to show an outright, event_ does.
What stays as first served
An event keeps the sport_, sport_ and competition_ it was first served with, on every route, for as long as it is served. A null competition_ can gain a key once; after that the key never changes for the event, and a key is never renamed or reused.
Teams, venue and event_ stay as first served while a bookmaker still lists the event that way. The one field that moves is commence_: when a fixture is rescheduled, it follows the exchange where one lists the event, else most bookmakers.
When these rules came in, on 13 and 14 November 2026, some events' values were corrected once and then held. The changelog lists the corrections.
Course names
venue is one string per course on every route, historical odds included. A UK or Irish course is plain: Cheltenham, Towcester. An overseas course carries a country tag, one spelling per country, such as (AUS), (NZL), (JPN) or (CAN): Doomben (AUS), Woodbine (CAN). A greyhound track is named without its meeting's words: Hove.
A course new to the feed can appear untagged until it is added, so a plain venue is not proof of a UK or Irish course.
Sport and competition keys
sport_ is the sport and the league its bookmakers file the event under: soccer_ for a Premier League match (its competition_ is soccer_, the key to send for the Premier League), and horse_ for a horse race. An event whose bookmakers name no competition is served under its sport's catch-all key, the sport's name twice, such as golf_, tennis_, cricket_ and greyhound_.
A catch-all sport_ can still carry a named competition_, so pick out a competition by competition_. It is null on every racing event, and usually on an event whose bookmakers' names for it identify no one competition (golf's catch-all events carry golf_).
A competition known under several keys comes back whole: sports= with any of its keys returns every event of it, on every route. New events carry one key for it, and an event already served keeps its own.
Looking an event up
GET / lists every event the API serves under one sport key or prefix, the matched boards' and raw's alike, with what names it (teams, venue or event_) and its competition_. has_ lists the matched boards carrying each event, and is [] for an event only raw serves.
Any sport the API serves, greyhound_ included, is a valid sport, and / lists it. eventIds, at most 50 ids, looks up any id the API serves, and an id merged into another returns the event it became.
It costs no tokens but needs a key. It pages 250 events at a time, in order of kick-off, then id, and a cursor expires 300 s after it was issued: dedupe by id.
# 1. Every greyhound race the API serves, free: has_coverage is [] for a race only raw serves curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \ "https://api.oddsrelay.io/v2/events?region=uk&sport=greyhound_racing" # 2. The ids you hold, comma-separated: an id merged into another returns the event it became curl --compressed -s -H "Authorization: Bearer $ODDSRELAY_KEY" \ "https://api.oddsrelay.io/v2/events?region=uk&sport=horse_racing&eventIds=$EVENT_IDS"
Every parameter: API reference.