> ## Documentation Index
> Fetch the complete documentation index at: https://docs.odds-api.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Live Events, Match Clock & Logos

> Fetch in-play events with live scores and a real-time match clock, and serve team logos straight from the API.

## Live Events

`GET /events/live` returns all currently in-play events, optionally filtered by sport:

```bash theme={null}
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:

```json theme={null}
{
  "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)                                                              |

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

```javascript theme={null}
// 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:

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

```javascript theme={null}
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:

```bash theme={null}
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](/guides/websockets)
* Fetch odds for live events with [Fetching Odds](/guides/fetching-odds)