Tutorial: from sport to live price
A complete walkthrough of the Odds API's request chain — pick a sport, list its competitions, drill into an event, list its markets, then read live prices. Every response below is a real, trimmed capture.
The Odds API is a hierarchy, not a single call: each step returns the ID you need for the next one. This walkthrough follows Cricket (sportId 4) all the way from “list the competitions” to “read the live price”, using the Cricket Odds API. The same chain works for every sport — only the sport ID changes (see Sport IDs).
List the competitions for a sport
Start from a sportId. This returns every competition currently carrying markets for that sport, each with its own competition.id — that’s what the next step needs.
curl -X GET 'http://xx.xx.xx.xx/api/betfair/competition-list/4'[
{
"competition": {
"id": "12444379",
"name": "The Ashes"
},
"competitionRegion": "International",
"marketCount": 1
},
{
"competition": {
"id": "12704140",
"name": "ICC Men's Cricket World Cup"
},
"competitionRegion": "International",
"marketCount": 1
},
{
"competition": {
"id": "101480",
"name": "Indian Premier League"
},
"competitionRegion": "IND",
"marketCount": 1
},
{
"competition": {
"id": "11679292",
"name": "County Championship"
},
"competitionRegion": "GBR",
"marketCount": 9
},
{
"competition": {
"id": "9992899",
"name": "International Twenty20 Matches"
},
"competitionRegion": "International",
"marketCount": 12
},
{
"competition": {
"id": "9962116",
"name": "One Day Internationals"
},
"competitionRegion": "International",
"marketCount": 79
}
]marketCount is a quick way to skip competitions with nothing currently priced. Pick one with markets — here, International Twenty20 Matches (competition.id 9992899).
List the events in that competition
Pass the sportId and the competitionId from step 1 to get every upcoming or in-play fixture in that competition, each with its own event.id.
curl -X GET 'http://xx.xx.xx.xx/api/betfair/event-list/4/9992899'[
{
"event": {
"id": "36099099",
"name": "Bahamas v Bermuda (Game 1)",
"countryCode": "GB",
"timezone": "Europe/London",
"openDate": "2026-09-25T15:00:00.000Z"
},
"isPremiumActive": "1",
"marketCount": 3
},
{
"event": {
"id": "36094846",
"name": "Cayman v Bahamas (Game 1)",
"countryCode": "GB",
"timezone": "Europe/London",
"openDate": "2026-09-24T15:00:00.000Z"
},
"isPremiumActive": "1",
"marketCount": 3
},
{
"event": {
"id": "36107226",
"name": "Cayman v Bahamas (Game 2)",
"countryCode": "GB",
"timezone": "GMT",
"openDate": "2026-09-24T19:30:00.000Z"
},
"isPremiumActive": "1",
"marketCount": 3
}
]openDate is the scheduled start time in UTC; isPremiumActive flags whether premium markets are open for that fixture. Take an event.id — here, 36099099 — into the next step.
List the markets on that event
Pass the eventId to get every market open on that fixture — match odds, completed match, tied match, and so on — each with its own marketId and its runners.
curl -X GET 'http://xx.xx.xx.xx/api/betfair/market-all-list/36099099'[
{
"marketId": "1.262709766",
"competition": {
"id": "9992899",
"name": "International Twenty20 Matches",
"provider": "BETFAIR"
},
"event": {
"id": "36099099",
"name": "Bahamas v Bermuda (Game 1)",
"countryCode": "GB",
"timezone": "Europe/London",
"openDate": "2026-09-25T15:00:00.000Z"
},
"eventType": {
"id": "4",
"name": "Cricket"
},
"marketName": "Completed Match",
"runners": [
{
"selectionId": 37302,
"runnerName": "Yes",
"handicap": 0,
"sortPriority": 1
},
{
"selectionId": 37303,
"runnerName": "No",
"handicap": 0,
"sortPriority": 2
}
],
"totalMatched": 1116.12,
"marketStartTime": "2026-09-25T15:00:00.000Z"
},
{
"marketId": "1.262709765",
"marketName": "Tied Match",
"totalMatched": 182.1
},
{
"marketId": "1.262709764",
"marketName": "Match Odds",
"runners": [
{
"selectionId": 2757231,
"runnerName": "Bahamas",
"handicap": 0,
"sortPriority": 1
},
{
"selectionId": 1266589,
"runnerName": "Bermuda",
"handicap": 0,
"sortPriority": 2
}
],
"totalMatched": 14506.5
}
]runners is what turns a price into something meaningful: each selectionId is one outcome (a team, a player, a “yes/no”), and that ID is what a price in the next step is keyed to. Take one or more marketIds — up to ten — into the final step.
Read the live price for those markets
This is the only POST in the chain: send up to ten marketIds from step 3 in one call and get back the current order book for each.
curl -X POST 'http://xx.xx.xx.xx/api/betfair/listMarketBook' \
-H 'Content-Type: application/json' \
-d '{"marketIds":["1.262709766","1.262709765","1.262709764"]}'{
"status": true,
"data": [
{
"marketId": "1.262709766",
"isMarketDataDelayed": false,
"status": "OPEN",
"betDelay": 0,
"complete": true,
"inplay": false,
"numberOfWinners": 1,
"numberOfRunners": 2,
"numberOfActiveRunners": 2,
"totalMatched": 1119.01,
"totalAvailable": 1352.19,
"runners": [
{
"selectionId": 37302,
"status": "ACTIVE",
"lastPriceTraded": 1.74,
"totalMatched": 546.44,
"ex": {
"availableToBack": [
{
"price": 1.07,
"size": 16.17
},
{
"price": 1.06,
"size": 377.79
},
{
"price": 1.01,
"size": 17.46
}
],
"availableToLay": [
{
"price": 6,
"size": 13.07
},
{
"price": 7,
"size": 10.03
},
{
"price": 110,
"size": 7.06
}
]
}
},
{
"selectionId": 37303,
"status": "ACTIVE",
"lastPriceTraded": 2.36,
"totalMatched": 572.57,
"ex": {
"availableToBack": [
{
"price": 1.33,
"size": 4.8
},
{
"price": 1.21,
"size": 6.33
},
{
"price": 1.2,
"size": 50
}
],
"availableToLay": [
{
"price": 18,
"size": 23.36
}
]
}
}
]
}
]
}Shown for one market only, to keep this page readable — a real response has one object per requested marketId in the same shape.
Per runner, ex.availableToBack and ex.availableToLay are the current order book — best price first on each side. lastPriceTraded and totalMatched tell you what actually changed hands. status at the top level (OPEN, SUSPENDED, CLOSED) is worth checking before you trust a price — a suspended market’s prices are stale by definition.
For a single market instead of a batch, see Market Odds by Id — same price shape, one marketId at a time, no request body.
Next
That’s the whole chain — competitions → events → markets → prices. From here:
- Access — get your servers’ IPs whitelisted, then poll prices as often as you need.
- Sport IDs — the IDs for every other sport this chain works with.
- Get Market Results — read the settled outcome once a market closes.
Test the API with live data
Run real requests in the Sportbex trial panel and see live responses.