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

# Events Channel - Live Match Events Stream

> Stream realtime match events via WebSocket. Goals, cards, substitutions, penalties, VAR and other in-game events with a canonical, sport-agnostic event model.

## What it streams

An **append-only log of in-play actions** for fixtures: goals, cards, corners, substitutions, penalties, VAR decisions, dangerous attacks, and more. Events feed timeline and coverage products; for grading/settlement use the resolved stats and settlement endpoints instead.

***

## Routing

* Entity key: `payload.fixtureId`
* Filters: `sportIds`, `tournamentIds`, `fixtureIds`
* Access: live/pregame access is determined by your `apiKey`

***

## Payload structure

Each message carries one or more event rows in the canonical event model:

| Field | Type | Description |
| - | - | - |
| `fixtureId` | `string` | The fixture this event belongs to |
| `source` | `string` | The event source (one authoritative source per sport — filter by it) |
| `providerEventId` | `string` | The source's own event ID — stable dedup/replay key |
| `eventType` | `string` | Action type (`goal`, `card_yellow`, `corner_taken`, `substitution`, `penalty_awarded`, `var`, …) — an [open taxonomy](https://docs.oddspapi.io/api-reference/enumerations.md#open-taxonomies-not-enums) |
| `period` | `string \| null` | The [period](https://docs.oddspapi.io/api-reference/enumerations.md#period) the event occurred in |
| `clockElapsed` | `string \| null` | Match clock at the event, as delivered (`mm:ss`) |
| `side` | `integer` | `1` = participant1, `2` = participant2, `0` = neutral/none (VAR, weather) |
| `playerId` | `integer \| null` | The player involved, when known |
| `value` | `number \| null` | Optional magnitude (e.g. score after the event, injury minutes) |
| `meta` | `object` | Additional provider detail |

***

## Semantics

* **Append-only.** Events are never updated or deleted. A correction is **itself an event** — e.g. a VAR overturn arrives as its own `eventType`, and `meta.corrects` may reference the corrected `providerEventId`.
* **Dedup on `(fixtureId, source, providerEventId)`.** Replays and reconnects can redeliver events; this key is idempotent.
* **One authoritative source per sport.** There is no cross-source merging of events — filter by `source` and use `entryId` for ordering and resume.
* `eventType` is an **open taxonomy**: new action types appear over time. Match the ones you support, ignore the rest.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.