---
title: Events & live scores
description: Match lists, live scores and the 12 per-match sub-resources — stats with xG, lineups, incidents, head-to-head, odds, predictions and more.
badge: free
---

# Events & live scores

An **event** is one match. The list endpoint answers "which matches", the
detail and sub-resources answer "everything about this match".

## List matches

```
GET /api/v2/events/
```

| Param | Type | Description |
|---|---|---|
| `league_id` | int | Filter by league |
| `season_id` | int | Filter by season (use for "this season's fixtures") |
| `team_id` | int | Matches of one team (home or away) |
| `team_name` | string | Fuzzy team-name filter when you don't have the id |
| `status` | string | `upcoming` · `live` · `finished` · `cancelled` · `postponed` |
| `date_from` / `date_to` | date | `YYYY-MM-DD` window (inclusive) |
| `limit` / `offset` | int | Pagination, default 50, max 200 |

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sports.bzzoiro.com/api/v2/events/?league_id=85&status=upcoming&limit=10"
```

## Live matches

```
GET /api/v2/events/live/
```

Optional `league_id`, `season_id`, `team_id`. Returns a compact live shape —
score, period, `current_minute`, half-time score, penalty shootout state —
plus two capability flags:

- `live_websocket` — this match can be followed on the
  [WebSocket](/docs/websocket/football/)
- `websocket_plus` — full per-action coverage (individual events with pitch
  coordinates) is available for it

Server-cached ~10–30 s; poll at 10 s or subscribe to the WebSocket.

## Match detail

```
GET /api/v2/events/{id}/
```

Everything static about the match: teams (ids + names), coaches, referee,
venue, round/group, kickoff time, scores (FT/HT/ET/pens), weather, pitch
condition, attendance, derby/neutral-ground flags, travel distance,
highlights and a head-to-head summary. Also `has_xg` (whether shot-level xG
exists for this match) and `previous_leg_event_id` — set when the match is
the second leg of a two-legged knockout tie, pointing at the first leg's
event id.

## Sub-resources

Every deeper view of a match is its own endpoint under
`/api/v2/events/{id}/…`:

| Endpoint | Returns |
|---|---|
| `/stats/` | Team stats (possession, shots, xG — per half where available), per-shot **shotmap**, momentum graph, average player positions, xG-per-minute series |
| `/lineups/` | Confirmed XI + bench, each player flagged `captain: true/false`; before lineups are announced, an AI-predicted XI with confidence scores (never predicted for live/finished matches) |
| `/incidents/` | Chronological goals, cards, substitutions, VAR decisions — each stamped with `period_second` for sub-minute ordering. Cards can carry `rescinded: true` when a card is overturned on review; overturned cards stay in the timeline but are excluded from card counts |
| `/player-stats/` | Per-player match statistics, including an `Advanced` category (big chances, xG on target, ball-carry progression, goalkeeper sweeper actions) |
| `/h2h/` | Past meetings, W/D/L, goals, win rates, recent results |
| `/odds/` | Consensus decimal odds per market |
| `/odds/comparison/` | Per-market × per-bookmaker grid |
| `/polymarket/` | Prediction-market implied probabilities (0–1) |
| `/prediction/` | Model probabilities per market (same shape as `/api/v2/predictions/{id}/`) |
| `/metadata/` | Kit colours, fun facts, AI-generated match preview |
| `/broadcasts/` | TV broadcasters, filterable by `country_code` |
| `/social/` | Curated tweets/videos for the match (`type` filter) |

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/v2/events/223510/stats/"
```

```json
{
  "event_id": 223510,
  "stats": {
    "home": { "possession": 54, "shots_total": 13, "shots_on_target": 5, "xg": 1.62, "...": "..." },
    "away": { "possession": 46, "shots_total": 9,  "shots_on_target": 3, "xg": 0.88, "...": "..." },
    "first_half": { "...": "..." }
  },
  "shotmap": [
    { "player_id": 40112, "minute": 23, "x": 88.2, "y": 44.1, "xg": 0.34, "result": "goal" }
  ],
  "momentum": [ { "minute": 1, "value": 12 }, { "minute": 2, "value": -4 } ],
  "average_positions": { "home": [ { "player_id": 40112, "x": 61.5, "y": 38.0 } ] },
  "xg_per_minute": [ { "minute": 23, "home": 0.34, "away": 0.0 } ]
}
```

> **Note:** shot-level xG and average positions exist for covered
> competitions; for others the arrays are empty rather than missing — code
> defensively either way.

## Typical patterns

- **Match center page:** detail + `/stats/` + `/incidents/` + `/lineups/` on
  load; then poll `/api/v2/events/live/?league_id=…` or use the
  [WebSocket](/docs/websocket/football/) for updates.
- **Fixtures widget:** list with `season_id` + `status=upcoming`, group by
  `round_number`.
- **Result + odds recap:** list with `status=finished` + `/odds/` per match.