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

# Event Catalogue

> Event and segment types returned by the Game Data API.

> [!WARNING]
>
> The Game Data API is in preview. Endpoints, fields and limits may change before release, and it is not yet available to call.

Events are moments, such as a pass or a high-speed run. Segments are spans of time that events sit inside, such as a phase of play or a possession. Every event shares the same envelope fields (see [List Game Events](https://docs.uplift.ai/api-reference/game-data/events/list.md)), and so does every segment (see [List Game Segments](https://docs.uplift.ai/api-reference/game-data/segments/list.md)). The fields specific to each type are in `attributes`. Select a type for its subtypes, attributes, units and an example.

## Events that involve the ball

These events need the ball as well as player positions: layer `ball`.

| Event | Short Description | `event_type` |
| - | - | - |
| [Pass](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/pass) | A pass from one player to another, with its outcome. | `pass` |
| [Shot](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/shot) | An attempt on goal. | `shot` |
| [Ball Win / Ball Loss](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/ball-win-loss) | Possession changing hands, and how. | `ball_win` / `ball_loss` |
| [Line Break](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/line-break) | A pass or carry that breaks a defensive line. | `line_break` |
| [On-Ball Engagement](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/on-ball-engagement) | A defender engaging the player with the ball. | `on_ball_engagement` |
| [Off-Ball Run](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/off-ball-run) | A run made while a teammate has the ball. | `off_ball_run` |
| [Passing Option](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/passing-option) | A teammate available to receive a pass. | `passing_option` |
| [Carry](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/carry) | A player moving with the ball. | `carry` |
| [Set Piece](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/set-piece) | Throw-ins, corners, goal kicks, free kicks, penalties and kick-offs. | `set_piece` |

## Events that need only player positions

These events come from player movement alone: layer `position`. Aerial duels are the exception: they need the ball's height. Per-player totals, such as distance and top speed, are in [Get Physical Summary](https://docs.uplift.ai/api-reference/game-data/physical/get.md).

| Event | Short Description | `event_type` |
| - | - | - |
| [High-Speed Running](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/high-speed-running) | An effort above high-speed running speed. | `high_speed_running` |
| [Acceleration / Deceleration](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/acceleration-deceleration) | A high-intensity change of speed. | `acceleration` / `deceleration` |
| [Change of Direction](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/change-of-direction) | A sharp cut at speed. | `change_of_direction` |
| [Duel](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/duel) | Two opponents contesting space or the ball at close range. | `duel` |
| [Fatigue Index](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/fatigue-index) | A player's freshness at a point in the game. | `fatigue_index` |
| [Team Shape](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/team-shape) | A team's shape and defensive line height, sampled over time. | `team_shape` |
| [Formation](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/formation) | A team's formation in a period. | `formation` |

## Events that need 3D body pose

These events come from players' 3D skeletons: layer `skeleton`.

| Event | Short Description | `event_type` |
| - | - | - |
| [Tackle](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/tackle) | A tackle, detected from 3D body pose. | `tackle` |
| [Player Down](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/player-down) | A player on the ground, detected from 3D body pose. | `player_down` |

## Segments

Phases of play and possessions cover the in-play timeline with no gaps, and stop during a dead ball. Key moments are analysis windows laid over the top.

| Segment | Short Description | `segment_type` |
| - | - | - |
| [Phase of Play](https://docs.uplift.ai/api-reference/game-data/event-catalogue/segments/phase-of-play) | A span of play with each team's phase, in and out of possession. | `phase_of_play` |
| [Team Possession](https://docs.uplift.ai/api-reference/game-data/event-catalogue/segments/team-possession) | From winning the ball to losing it. | `team_possession` |
| [Player Possession](https://docs.uplift.ai/api-reference/game-data/event-catalogue/segments/player-possession) | One player's spell on the ball, from first touch to release. | `player_possession` |
| [Key Moment](https://docs.uplift.ai/api-reference/game-data/event-catalogue/segments/key-moment) | A passage selected for closer analysis, such as a fast break. | `key_moment` |
| [Overload](https://docs.uplift.ai/api-reference/game-data/event-catalogue/segments/overload) | More attackers than defenders in an area, for as long as it lasts. | `overload` |
| [Dead Ball](https://docs.uplift.ai/api-reference/game-data/event-catalogue/segments/dead-ball) | A span when the ball is out of play. | `dead_ball` |

## How events and segments fit together

* Every event carries `phase`, `team_possession_id` and `player_possession_id`, copied from the segments it falls in, so you can filter events without joining to segments. `phase` is the in-possession phase.
* An event that crosses a boundary, such as a run that starts in one phase and ends in the next, belongs to the segment where it starts.
* Events that don't involve the ball, such as high-speed runs, changes of direction and ground duels, still get a `phase`. They only get possession IDs when the ball is tracked.
* Key moments list their events in `event_ids`. They are never used to filter or count events.


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