Skip to main content

​
Live Events

GET /events/live returns all currently in-play events, optionally filtered by sport: 
curl "https://api.odds-api.io/v3/events/live?sport=football&apiKey=YOUR_KEY"
Each event includes live scores and, where available, a clock object with the current match clock. The same clock field also appears on live events returned by GET /events?status=live and GET /events/{id}.

​
The Clock Object

Live events carry an optional clock field: 
{
  "id": 65068198,
  "home": "Manchester City",
  "away": "Liverpool FC",
  "status": "live",
  "scores": { "home": 1, "away": 0 },
  "clock": {
    "minute": 67,
    "playedSeconds": 4023,
    "period": 2,
    "running": true,
    "statusDetail": "2nd half",
    "injuryTime": 4
  }
}
FieldTypeDescription
minuteintegerCumulative match minute (elapsed play, not time remaining)
playedSecondsintegerSeconds of play elapsed
periodintegerCurrent period number (half, quarter, set)
runningbooleanWhether the clock is currently ticking
statusDetailstringHuman-readable phase, e.g. "2nd half", "Break"
servestring"home" or "away": the current server, or in turn-based sports (snooker, darts) the player at the table
injuryTimeintegerAnnounced stoppage time in minutes (football)
A few things to know:
  • clock is omitted entirely when no clock data is available for an event. Treat it as optional.
  • minute and playedSeconds are extrapolated server-side from the live feed, so they stay accurate even when the response is served from cache.
  • The clock only advances while running is true. During half-time and other breaks it freezes at the last played second.
  • For a per-second ticker in your UI, extrapolate client-side from playedSeconds at the moment you received the response, while running is true.
// Per-second client-side ticker
const receivedAt = Date.now();
function currentSeconds(clock) {
  if (!clock.running) return clock.playedSeconds;
  return clock.playedSeconds + Math.floor((Date.now() - receivedAt) / 1000);
}

​
statusDetail values

statusDetail is the live feed’s phase description passed through as-is. The exact strings vary by sport; treat it as display text rather than an enum, and use period + running for any betting logic. Values you can expect:
SportTypical values
Football"1st half", "Halftime", "2nd half", "Awaiting extra time", "Penalties"
Basketball"1st quarter" … "4th quarter", "Break"
Tennis, volleyball, badminton"1st set", "2nd set", "3rd set", …
Esports"Map 1", "Map 2", "Map 3", …
Baseball"1st inning" … "9th inning" (no clock seconds; baseball is untimed)
Cricket"First innings, home team", …
Snooker, darts"Started"

​
Rendering a football clock the conventional way

minute is cumulative elapsed play, so first-half stoppage time reads 46, 47, 48… To render the conventional 45+X / 90+X style, cap the minute at the period boundary: 
function displayMinute(clock) {
  const cap = clock.period === 1 ? 45 : 90;
  if (clock.period <= 2 && clock.minute > cap) {
    return `${cap}+${clock.minute - cap}`; // e.g. "45+3"
  }
  return `${clock.minute}`;
}
injuryTime carries the announced stoppage minutes when the fourth official raises the board, so 45+2 with injuryTime: 4 tells you about two more minutes of the half remain.

​
Participant Logos

GET /participants/{id}/logo returns the team or player crest as a PNG, served directly from the Odds-API domain: 
curl "https://api.odds-api.io/v3/participants/38/logo?apiKey=YOUR_KEY" -o crest.png
Use the homeId / awayId fields from event responses as the participant id, or look ids up via GET /participants.
  • Responses include Cache-Control: public, max-age=86400, so browsers and CDNs cache them for a day. You can hotlink the URL in an <img> tag.
  • Returns 404 when no logo exists for the participant. Misses are cached server-side, so repeated lookups for logo-less participants stay fast.
  • Logos are served from our infrastructure; no third-party provider URLs are exposed to your users.

​
Next Steps

  • Stream live scores and match status over WebSocket instead of polling, see the WebSocket guide
  • Fetch odds for live events with Fetching Odds