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

# Game Data Overview

> Events, phases, possessions, physical summaries and tracking from match video.

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

The Game Data API returns what Uplift produces from match video: events, phases of play and possessions, physical summaries per player, and tracking for every player and the ball. It uses the same base URL, API keys, errors and conventions as the rest of the Uplift API.

## How it is organized

The API has two tiers:

* **Per game.** Each endpoint returns a whole game in one response: every event, every segment, or every player's physical summary. Optional filters narrow the result. Tracking is returned one period at a time.
* **Across games.** [List Player Stats](https://docs.uplift.ai/api-reference/game-data/player-stats/list.md) aggregates physical and event totals per player, grouped by game or season.

To add a game, [create the game](https://docs.uplift.ai/api-reference/game-data/games/create.md), then [create a clip](https://docs.uplift.ai/api-reference/game-data/clips/create.md) and upload the video. When processing finishes, the game's data is available from the per-game endpoints.

## Key concepts

* **Game:** a match between two teams, with date, competition, pitch size, frame rate (`fps`), roster and each team's attacking direction per period. Each team has a stable `team_id` and a `team_side` of `home` or `away`.
* **Clip:** a video uploaded to a game. A game can be one full-match video or several clips.
* **Run:** one processing pass over a game's clips. Every response includes the `run_id` it came from. Re-processing a game creates a new run and replaces the game's data.
* **Event:** a moment in the game, such as a pass, a high-speed run or a duel. See the [event catalogue](https://docs.uplift.ai/api-reference/game-data/event-catalogue.md).
* **Segment:** a span of time, such as a phase of play, a team possession, a player possession or a key moment. Every event falls inside a phase of play and, when the ball is involved, a team possession and a player possession.
* **Player:** `player_id` identifies a roster entry in one game. It can be empty, or a placeholder such as `track_12`, when a player isn't identified. When it is linked to an Uplift athlete, `athlete_id` is included, so game data and capture data can be joined.

## Conventions

* **Coordinates:** pitch metres with the origin at the centre spot, `x` along the length and `y` across; `z` is height for the ball. Event coordinates are turned so that the event's team attacks towards positive `x`; `attacking_side` says which way that team was attacking on the pitch. Tracking stays on the fixed pitch, with each team's attacking direction per period on the game.
* **Time:** `period` is 1 or 2 for halves, 3 or 4 for extra time and 5 for a penalty shootout; a single clip is period 1. `time_s` is seconds from the start of the period; `frame` is the video frame.
* **Frame rate:** data is at the game's frame rate, given in `fps` on the game.
* **Naming:** every field, parameter and value is `snake_case`.
* **Paging:** per-game endpoints return the whole game. List endpoints use `limit` and `offset`: List Games returns up to 500 rows per page, List Player Stats up to 5,000.
* **Quality:** every event and segment has a `confidence` from 0 to 1, a `confidence_tier` (`high`, `medium` or `low`), and the `layer` it needs: `position` (player positions only), `ball` (the ball as well) or `skeleton` (3D body pose).
* **Formats:** responses are JSON. Tracking is a zstd-compressed Parquet file.

## Webhooks

Game data uses the existing [webhooks](https://docs.uplift.ai/guides/platform-configuration/setting-up-webhooks-in-the-uplift-platform.md):

* `game.processing_completed`: a run finished, the first time or after re-processing. The payload includes `game_id` and `run_id`.
* `game.processing_failed`: processing failed, with an error summary.


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