# Events

Events in a football match are crucial moments that define the course and outcome of the fixture. Each event type is represented by a unique code, allowing you to track and analyse various events during a match. Here's how you can use the `events` include to retrieve detailed information about specific events in a fixture.

### How to use this include

To include events in your API requests, add the `&include=events` parameter. For example, in a[ GET Fixture by ID](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/fixtures#get-fixture-by-id) request, the URL would look like this:

```http
https://api.sportmonks.com/v3/football/fixtures/{fixture_ID}
?api_token=YOUR_TOKEN&include=events
```

### How does it work?

The `events` include provides comprehensive information about every significant moment during a match.

**Core fields in the response:**

* **id**: Unique identifier for the event
* **fixture\_id**: The fixture (match) this event belongs to
* **period\_id**: The period when the event occurred
* **team\_id**: The team involved in the event
* **player\_id**: The player involved in the event
* **related\_player\_id**: Secondary player (e.g., assist provider, player coming off in substitution)
* **player\_name**: Name of the primary player
* **related\_player\_name**: Name of the related player
* **minute**: When during the match the event occurred
* **extra\_minute**: Additional minutes (injury time) if applicable
* **result**: The match score at the time of the event (when applicable)
* **info**: Details about the event (e.g., "Header", "Foul", "Offside check")
* **sort\_order**: **Critical** - Chronological ordering of events. Always use this to sort events, not the minute field

### Types of events

#### Goal events

**GOAL** - When a goal is scored during play

* `player_id` = Goal scorer
* `related_player_id` = Assist provider (can be null if unassisted)
* `result` = Updated match score

**OWN GOAL** - When a defensive error results in an own goal

* `player_id` = Player making the error
* `result` = Updated match score

#### Card events

**YELLOWCARD** - Player receives a yellow card

* `player_id` = Player receiving the card
* `info` = Reason (e.g., "Foul", "Unsporting behaviour")

**REDCARD** - Player receives a direct red card

* `player_id` = Player receiving the card
* Results in immediate ejection

**YELLOWREDCARD** - Second yellow card resulting in red

* `player_id` = Player receiving second yellow
* Automatic ejection

#### Penalty events

**PENALTY** - Penalty goal scored during play

* `player_id` = Penalty taker
* `result` = Updated match score

**MISSED\_PENALTY** - Penalty missed or saved

* `player_id` = Penalty taker

**PENALTY\_SHOOTOUT\_GOAL** - Goal during penalty shootout

* `player_id` = Penalty taker
* `result` = Shootout score

**PENALTY\_SHOOTOUT\_MISS** - Missed penalty in shootout

* `player_id` = Penalty taker

#### Substitution events

**SUBSTITUTION** - Player substitution

* `player_id` = Player coming ON the field
* `related_player_id` = Player coming OFF the field
* Important: These are reversed from some other events

#### VAR events

**GOAL\_UNDER\_REVIEW** - VAR check initiated for a goal

* Indicates a goal is being reviewed
* Followed by either GOAL\_CONFIRMED or GOAL\_DISALLOWED

**GOAL\_CONFIRMED** - Goal upheld after VAR review

* Initially awarded goal confirmed as valid

**GOAL\_DISALLOWED** / **GOAL\_CANCELLED** - Goal cancelled by VAR

* Initial goal is disallowed
* Usually due to offside, foul, or handball

**VAR\_CARD** - VAR review of a card incident

* Indicates VAR reviewed a potential card decision

**PENALTY\_CONFIRMED** - Penalty upheld after VAR review

* Initially awarded penalty confirmed

**PENALTY\_DISALLOWED** - Penalty cancelled by VAR

* Initial penalty decision reversed

### Important: Using sort\_order for correct event sequencing

**Always sort events by `sort_order`, not `minute`.** Multiple events can occur at the same minute, but `sort_order` ensures they are displayed in correct chronological sequence.

```js
// Correct
events = events.sort((a, b) => a.sort_order - b.sort_order);

// Incorrect (may mess up sequence)
// events = events.sort((a, b) => a.minute - b.minute);
```

#### VAR Event Chains Example

Multiple related events can occur in sequence. For instance, when a goal is reviewed:

1. **Minute 54 (sort\_order: 15)**: GOAL event - Goal is initially scored
2. **Minute 54 (sort\_order: 16)**: GOAL\_UNDER\_REVIEW - VAR check initiated
3. **Minute 54 (sort\_order: 17)**: GOAL\_DISALLOWED - VAR cancels the goal

All three events share the same `minute` but differ in `sort_order`. This is why sorting by `sort_order` is critical.

### Handling null values

**related\_player\_id can be null** when:

* A goal is scored with no assist
* A card is issued (no secondary player)
* Most non-substitution events

**result is null** for:

* Card events
* Substitutions
* VAR reviews (until decision)

**extra\_minute is null** for:

* Events before injury time

Handle gracefully in your code:

```js
assist = event.related_player_name ? `(${event.related_player_name})` : "";
score = event.result || "Match ongoing";
time_str = event.extra_minute ? `${event.minute}+${event.extra_minute}'` : `${event.minute}'`;
```

### Example responses

#### Goal with assist

```json
{
  "id": 152213481,
  "fixture_id": 19568543,
  "period_id": 6379831,
  "team_id": 3321,
  "player_id": 160208,
  "related_player_id": 37912237,
  "player_name": "Alejandro Grimaldo",
  "related_player_name": "Christian Kofane",
  "result": "1-0",
  "info": "Left foot shot",
  "minute": 23,
  "extra_minute": null,
  "sort_order": 1
}
```

#### Substitution event

```json
{
  "id": 152214074,
  "fixture_id": 19568543,
  "period_id": 6379936,
  "team_id": 9,
  "player_id": 336133,
  "related_player_id": 37459073,
  "player_name": "Phil Foden",
  "related_player_name": "Rico Lewis",
  "minute": 46,
  "extra_minute": null,
  "sort_order": 2
}
```

#### Yellow card event

```json
{
  "id": 152214396,
  "fixture_id": 19568543,
  "period_id": 6379936,
  "team_id": 3321,
  "player_id": 160208,
  "related_player_id": null,
  "player_name": "Alejandro Grimaldo",
  "related_player_name": null,
  "info": "Foul",
  "minute": 60,
  "extra_minute": null,
  "sort_order": 5,
  "rescinded": false
}
```

### Other include options

In addition to the `events` include, you can use nested includes to retrieve more detailed data. For more information about nested includes, see this [page](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/enrich-your-response/nested-includes).

The following nested includes are commonly used with events:

**`events.type`** - Returns detailed type information for each event

* Provides event classification and metadata
* Minimal size increase

**`events.subType`** - Returns detailed event sub-type information

* For example, the specific type of shot (header, left foot, right foot)
* Useful for detailed shooting analysis

**`events.player`** - Returns full player information for the primary player

* Includes player profile, nationality, physical attributes
* Increases response size significantly

**`events.relatedPlayer`** - Returns full player information for the secondary player

* For assist providers, players coming off, etc.
* Increases response size significantly

Example combined request:

```http
?include=events.type,events.player,events.relatedPlayer
```

This would provide event types, full player details for both the primary and secondary players in a single request.

### Best practices

1. **Always sort by sort\_order**: This ensures correct event sequencing, especially when multiple events occur at the same match minute.
2. **Use nested includes sparingly**: Adding player includes significantly increases response size. Only include what you need.
3. **Handle VAR event chains**: Expect that VAR-related events come in sequences. Don't assume a GOAL event is final, check for subsequent VAR events.
4. **Check for null fields**: Always validate `related_player_id`, `result`, `extra_minute`, and `info` before using them.
5. **Cache completed matches**: Once a match reaches final state, events don't change. Cache these responses permanently.

### See also

#### Prerequisites

* [Fixtures Tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/fixtures) - Access fixture events
* [Includes Tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes) - Using the events include

#### Related data

* [Lineups](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/lineups-and-formations) - Link events to players
* [Players](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/teams-players-coaches-and-referees) - Player information for events
* [Statistics](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/statistics) - Events generate statistics

#### Understanding events

* [Types Reference](https://docs.sportmonks.com/v3/definitions/types/events) - All event type IDs
* [States](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/states) - Event states (confirmed, under review, etc.)
* [Periods](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/periods) - Match period information

#### Building with events

* [Livescores](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/livescores-and-fixtures/livescores) - Real-time event updates
* [Filter and Select](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/filter-and-select-fields) - Filter by event type

#### Related includes

* [States](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/states) - Current match state works alongside events to give context
* [Periods](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/periods) - Period information complements event data
* [Lineups](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/lineups) - Cross-reference players with lineup data
* [Participants](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/participants) - Team information relevant to events

#### API reference

* [Fixture Entity](https://docs.sportmonks.com/v3/endpoints-and-entities/entities/fixture) - Event includes documentation


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.