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

# On-Ball Engagement

> A defender engaging the player with the ball.

> [!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:** `on_ball_engagement`
* **Subtypes:** `pressure`, `pressing`, `counter_press`, `recovery_press`, `other`
* **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=on_ball_engagement`

## Description

A defender engaging the player with the ball. The event's `player_id` is the defender. The subtype says how: `pressure` on the player with the ball; `pressing`, coordinated pressure on successive possessions; `counter_press`, a press that starts straight after losing the ball; `recovery_press`; or `other`.

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 |
| - | - | - |
| `target_player_id` | — | Player with the ball who was engaged. |
| `pressure_level` | 1–5 | How much pressure was applied, from 1 (least) to 5 (most). |
| `min_distance_m` | m | Closest distance between the defender and the player with the ball. |
| `closing_speed_kmh` | km/h | Speed at which the defender closed in. |
| `players` | — | Pressing subtypes. Players taking part in the press. |
| `possessions_pressed` | count | Pressing subtypes. Number of successive possessions pressed. |
| `seconds_after_loss` | s | `counter_press` only. Time between losing the ball and the start of the press. |
| `outcome` | — | Result of the engagement, for example `forced_backward` or `ball_win`. |

## Example

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

```json theme={null}
{
  "event_type": "on_ball_engagement",
  "event_subtype": "pressure",
  "player_id": "a06",
  "attributes": {
    "target_player_id": "p07",
    "pressure_level": 4,
    "min_distance_m": 1.4,
    "closing_speed_kmh": 16.6,
    "outcome": "forced_backward"
  }
}
```

```json theme={null}
{
  "event_type": "on_ball_engagement",
  "event_subtype": "counter_press",
  "team_id": "t-0388",
  "team_side": "away",
  "attributes": {
    "players": [
      "a06",
      "a08",
      "a10"
    ],
    "possessions_pressed": 3,
    "seconds_after_loss": 1.2,
    "outcome": "ball_win"
  }
}
```

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