Live Events, Match Clock & Logos

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
  }
}

Field	Type	Description
`minute`	integer	Cumulative match minute (elapsed play, not time remaining)
`playedSeconds`	integer	Seconds of play elapsed
`period`	integer	Current period number (half, quarter, set)
`running`	boolean	Whether the clock is currently ticking
`statusDetail`	string	Human-readable phase, e.g. `"2nd half"`, `"Break"`
`serve`	string	`"home"` or `"away"`: the current server, or in turn-based sports (snooker, darts) the player at the table
`injuryTime`	integer	Announced stoppage time in minutes (football)
`periodStartedAt`	integer	Unix timestamp (seconds) when the current period started. Only sent when there is no played clock, never alongside `playedSeconds`

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.
Within a period, backward feed corrections freeze the served clock at its last value with running: false until the feed catches up. The hold does not expire into a backward jump. A change of period resets the floor immediately.
For a per-second ticker in your UI, extrapolate client-side from playedSeconds at the moment you received the response, while running is true.
On WebSocket, the clock rides on live score/status messages, but those fire only on real events. Seed the initial clock with one GET /events/live on connect, then let the WebSocket re-anchor it.
Some events have no played clock at all, for example ice hockey games with basic coverage. Their clock carries period and statusDetail only, plus periodStartedAt when the feed reports when the period began. That is wall time, not game time: a hockey clock stops at every whistle, so the time since periodStartedAt is longer than the time played. Show it as elapsed wall time (for example “P1, started 12m ago”), never as playedSeconds. It is omitted when missing, in the future, or more than 3 hours old, and it also appears in WebSocket clock snapshots.

{
  "clock": {
    "period": 1,
    "running": false,
    "statusDetail": "1st period",
    "periodStartedAt": 1792170000
  }
}

// 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);
}

Period Scores

Every event’s scores object has the headline home/away plus a periods map. The keys are the same for every sport and every source, on /events, /historical, /settlements and WebSocket score and status messages:

Key	Meaning
`p1`, `p2` … `pN`	Score in that period only: halves, quarters, periods, innings, or games in a set
`ft`	Running total at the end of regulation. In set sports such as tennis and volleyball, sets won
`ot`	Running total after overtime or extra time, regulation included. Only when overtime was played
`ap`	Running total after a penalty shootout, shootout goals included. Only when there was a shootout
`currentgame`	Live tennis only: points in the game being played
`map1` … `mapN`, `map1_score` …	Esports maps, see Esports Events
`inning1`, `inning2` …	Cricket innings, see Cricket Scores

The headline score never includes a penalty shootout. It is the result after overtime when there was overtime, otherwise the result after regulation. To get one part on its own:

overtime or extra time alone: ot minus ft
the shootout alone: ap minus ot (or minus ft when there was no extra time). In ice hockey the provider usually counts the shootout as one deciding goal for the winner, so this reads 1-0 or 0-1.

ft, ot and ap are written once that phase is over, and only when the source reports them, so treat every key as optional. A football cup tie that went to extra time and penalties:

"scores": {
  "home": 3,
  "away": 3,
  "periods": {
    "p1": { "home": 0, "away": 0 },
    "p2": { "home": 3, "away": 3 },
    "ft": { "home": 3, "away": 3 },
    "ot": { "home": 3, "away": 3 },
    "ap": { "home": 6, "away": 7 }
  }
}

The match was 3-3 after 90 minutes and after extra time, and the away side won the shootout 4-3. A basketball game decided in overtime:

"scores": {
  "home": 77,
  "away": 72,
  "periods": {
    "p1": { "home": 12, "away": 16 },
    "p2": { "home": 22, "away": 16 },
    "p3": { "home": 18, "away": 14 },
    "p4": { "home": 14, "away": 20 },
    "ft": { "home": 66, "away": 66 },
    "ot": { "home": 77, "away": 72 }
  }
}

Some events also carry older spellings next to these keys: period1 to period5, overtime and penalties (and fulltime on some older historical events). Read the keys above instead. The older spellings stop on 12 November 2026, 09:00 UTC. See the changelog.

Cricket Scores

Cricket has no match clock, so live cricket events carry no clock object. The per-innings detail lives in scores.periods instead, keyed inning1, inning2 and so on:

{
  "id": 71173666,
  "home": "Antigua And Barbuda Falcons",
  "away": "Barbados Tridents",
  "status": "live",
  "scores": {
    "home": 155,
    "away": 125,
    "periods": {
      "inning1": {
        "home": 155,
        "away": 125,
        "wickets": { "home": 6, "away": 9 },
        "overs":   { "home": 20, "away": 20 }
      }
    }
  }
}

Field	Type	Description
`home` / `away`	integer	Runs scored by each side in this innings
`wickets`	object	Wickets lost by each side in this innings
`overs`	number	Overs bowled, in cricket notation: `19.3` is nineteen overs and three balls

A few things to know:

wickets and overs are cricket only. They are omitted for every other sport, so existing period scores keep exactly their home/away shape.
Both are omitted when the source does not publish them, so treat them as optional even on cricket.
A side that has not yet batted reads 0, not a missing key.
Coverage varies by competition. Major internationals and the larger franchise leagues carry full innings detail; smaller domestic competitions may return a match-level score with no periods at all.

`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:

Sport	Typical 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.
Esports teams are covered as well as traditional sports.

Esports Events

Esports events carry an extra esports object on /events, /events/live, /events/search and /events/{id}. It is absent for every other sport.

{
  "id": 6355510210,
  "home": "100 Thieves",
  "away": "G2 Esports",
  "homeId": 9003572165653,
  "awayId": 9002805226862,
  "sport": { "name": "Esports", "slug": "esports" },
  "league": { "name": "Valorant - VCT Champions", "slug": "valorant-vct-champions" },
  "esports": {
    "game": { "name": "Valorant", "slug": "valorant" },
    "league": { "name": "VCT", "slug": "valorant-vct" },
    "region": "Asia",
    "format": { "type": "bestOf", "games": 5 }
  }
}

Field	Description
`game`	The game being played.
`league`	The parent league, such as VCT, LCK or LEC. Its `slug` stays the same across the league’s splits and stages, so use it to group events. The top-level `league` names the stage.
`region`	`Western Europe`, `Eastern Europe`, `North America`, `South America`, `Asia`, `Oceania` or `Middle East`. Omitted when unknown.
`format`	`type` is `bestOf` or `firstTo` and `games` is the number, so `bestOf` with `3` is a best of 3. Omitted when unknown.

Esports teams

GET /participants?sport=esports adds two fields to each team: game, the slug of the game the team plays, and shortCode when one is known.

{ "id": 9002805226862, "name": "G2 Esports", "sport": "esports", "game": "valorant", "shortCode": "G2" }

An organisation that fields teams in several games has one participant per game, so a name like G2 Esports appears more than once. Use game to tell them apart, and always take the id from the event’s homeId / awayId when you need the team that is actually playing.

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

Getting Started

Guides

Examples

Live Events, Match Clock & Logos

Live Events

The Clock Object

Period Scores

Cricket Scores

`statusDetail` values

Rendering a football clock the conventional way

Participant Logos

Esports Events

Esports teams

Next Steps

​Live Events

​The Clock Object

​Period Scores

​Cricket Scores

​statusDetail values

​Rendering a football clock the conventional way

​Participant Logos

​Esports Events

​Esports teams

​Next Steps

Live Events

The Clock Object

Period Scores

Cricket Scores

`statusDetail` values

Rendering a football clock the conventional way

Participant Logos

Esports Events

Esports teams

Next Steps