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

# Ball Win / Ball Loss

> Possession changing hands, and how.

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

## Technical Details

* **Variable Type:** Event
* **Event Types:** `ball_win`, `ball_loss`
* **Subtypes:** `interception`, `pass_intercepted`, `challenge`, `recovery`, `loose_ball`
* **Layer:** `ball` (ball and player positions)
* **Returned By:** [List Game Events](https://docs.uplift.ai/api-reference/game-data/events/list.md)
* **Filter:** `event_type=ball_win,ball_loss`

## Description

Possession changing hands, and how. The team that gains the ball gets a `ball_win`; the team that gives it up gets a `ball_loss`. The subtype says how it happened, from each side: `interception` and `pass_intercepted`, `challenge`, or `recovery` and `loose_ball`.

The two counts measure how much the win changes the picture: opponents now behind the ball, and teammates brought into play.

Every event has the same envelope fields, including time, frames, player, team, pitch coordinates, `phase`, `team_possession_id`, `player_possession_id` and `confidence`. See [List Game Events](https://docs.uplift.ai/api-reference/game-data/events/list.md). The fields below are specific to this type and are returned in `attributes`.

## Attributes

| Field | Units | Description |
| - | - | - |
| `lost_by_player_id` | — | Player who lost the ball. |
| `opponents_removed` | count | Opponents taken out of the game by winning the ball. |
| `teammates_added` | count | Teammates brought into play by winning the ball. |

## Example

Only the type-specific fields and a few envelope fields are shown.

```json theme={null}
{
  "event_type": "ball_win",
  "event_subtype": "interception",
  "x_start": 8.2,
  "y_start": -14.0,
  "attributes": {
    "lost_by_player_id": "a04",
    "opponents_removed": 5,
    "teammates_added": 2
  }
}
```

## Related

* [Team Possession](https://docs.uplift.ai/api-reference/game-data/event-catalogue/segments/team-possession)
* [On-Ball Engagement](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/on-ball-engagement)


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