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

# Team Possession

> From winning the ball to losing it.

> [!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:** Segment
* **Segment Type:** `team_possession`
* **Returned By:** [List Game Segments](https://docs.uplift.ai/api-reference/game-data/segments/list.md)
* **Filter:** `segment_type=team_possession`

## Description

One team's possession, from winning the ball to losing it. A team possession usually spans several phases and is made up of player possessions.

Every segment has the same envelope fields: time, frames, team, player, `confidence` and `layer`. See [List Game Segments](https://docs.uplift.ai/api-reference/game-data/segments/list.md). The fields below are specific to this type and are returned in `attributes`.

## Attributes

| Field | Units | Description |
| - | - | - |
| `started_by` | — | How the possession started: `ball_win`, `dead_ball`, `ball_unseen`, `contested` or `clip_start`. |
| `ended_by` | — | How the possession ended: `ball_loss`, `dead_ball`, `ball_unseen`, `contested` or `clip_end`. |
| `passes` | count | Passes in the possession. |
| `player_possessions` | count | Player possessions in the possession. |
| `phases` | — | Phases of play the possession went through, in order. |
| `max_x_reached_m` | m | Furthest point up the pitch the ball reached, as an `x` coordinate. |

## Example

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

```json theme={null}
{
  "segment_type": "team_possession",
  "segment_id": "tpos-0088",
  "team_id": "t-0451",
  "team_side": "home",
  "attributes": {
    "started_by": "ball_win",
    "ended_by": "ball_loss",
    "passes": 7,
    "player_possessions": 8,
    "phases": [
      "build_up",
      "create",
      "finish"
    ],
    "max_x_reached_m": 41.2
  }
}
```

## Related

* [Ball Win / Ball Loss](https://docs.uplift.ai/api-reference/game-data/event-catalogue/events/ball-win-loss)
* [Player Possession](https://docs.uplift.ai/api-reference/game-data/event-catalogue/segments/player-possession)


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