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

# Duel

> Two opponents contesting space or the ball at close range.

> [!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 Type:** `duel`
* **Subtypes:** `ground`, `aerial`
* **Layer:** `position` for `ground` (player positions only); `ball` for `aerial`
* **Returned By:** [List Game Events](https://docs.uplift.ai/api-reference/game-data/events/list.md)
* **Filter:** `event_type=duel`

## Description

Two opponents contesting space or the ball at close range. A `ground` duel is two opponents within 1.5 m of each other while both are moving. An `aerial` duel is two players contesting a high ball, and needs the ball's height as well as player positions.

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 |
| - | - | - |
| `players` | — | The two players in the duel. |
| `min_distance_m` | m | Closest distance between them. |
| `pair_speed_mps` | m/s | Speed of the pair during the duel. |
| `ball_distance_m` | m | Distance from the pair to the ball. |
| `ball_contested` | — | Whether the ball was being contested. |
| `duration_s` | s | Length of the duel. |
| `winner_player_id` | — | Player who won the duel, when known. |
| `ball_height_m` | m | `aerial` only. Height of the ball when it was contested. |
| `header` | — | `aerial` only. Whether the ball was headed. |
| `header_outcome` | — | `aerial` only. What the header did, for example `pass_to_teammate`. |

## Example

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

```json theme={null}
{
  "event_type": "duel",
  "event_subtype": "ground",
  "attributes": {
    "players": [
      "p08",
      "a06"
    ],
    "min_distance_m": 0.9,
    "pair_speed_mps": 4.1,
    "ball_contested": true,
    "duration_s": 1.1
  }
}
```

```json theme={null}
{
  "event_type": "duel",
  "event_subtype": "aerial",
  "attributes": {
    "players": [
      "p05",
      "a04"
    ],
    "ball_height_m": 2.1,
    "winner_player_id": "p05",
    "header": true,
    "header_outcome": "pass_to_teammate"
  }
}
```

## Related

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


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