Event Property Filter

Filter intervals by event metadata properties. This is the most flexible filter for v3 data — query any event type by its metadata fields with equality, set membership, or numeric thresholds.

Requires Data Version 3+

This filter requires analysis data version 3 or later. Use the Schema endpoint to check available properties for a specific analysis.

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Must be `"event_property"`
`event_type`	string	Yes	Event type to filter (e.g. `"pass"`, `"tackle"`, `"shot"`)
`properties`	array	Yes	List of property constraints (AND-combined)
`players`	array	No	Player IDs (e.g., `["0-5", "1-13"]`)
`teams`	array	No	Teams: `"team_0"`, `"team_1"`

Property Constraints

Each entry in properties filters on a single metadata field:

Field	Type	Description
`field`	string	Metadata field name (e.g. `"set_piece"`, `"length_cm"`)
`eq`	any	Exact match
`in_`	array	Match any value in the list
`gte`	number	Greater than or equal
`lte`	number	Less than or equal

Multiple constraints are AND-combined: all must be true for an event to match.

Available Properties

pass

Property	Type	Description	Values
`body_part`	`str`	Which body part contacted the ball. `unknown` is the engine-side placeholder for unmeasured rows.	`head`, `both_hands`, `unknown`
`confidence_detection`	`float32`	Detection confidence [0,1].	numeric
`confidence_event`	`float32`	Event [0,1]. Model confidence for this event class.	numeric
`confidence_identity`	`float32`	Identity confidence [0,1]. Null for non-actor events and for rows where the jersey/player_id was not resolved (team-only actor rows have this null).	numeric
`length_cm`	`int32`	Euclidean distance start → target, in cm (span events).	numeric
`pass_type`	`str`	Stylistic flavour for a `pass` event (e.g. `cross`). null for plain passes.	`cross`
`set_piece`	`str`	Restart context for a `pass` event. `open_play` is the in-play default.	`open_play`, `throw_in`, `kick_off`, `corner_kick`, `free_kick`, `goal_kick`
`x_target`	`int16`	Target x-coordinate in cm (corner-origin, same convention as top-level x/y).	numeric
`y_target`	`int16`	Target y-coordinate in cm (corner-origin, same convention as top-level x/y).	numeric

drive

Property	Type	Description	Values
`body_part`	`str`	Which body part contacted the ball. `unknown` is the engine-side placeholder for unmeasured rows.	`head`, `both_hands`, `unknown`
`confidence_detection`	`float32`	Detection confidence [0,1].	numeric
`confidence_event`	`float32`	Event [0,1]. Model confidence for this event class.	numeric
`confidence_identity`	`float32`	Identity confidence [0,1]. Null for non-actor events and for rows where the jersey/player_id was not resolved (team-only actor rows have this null).	numeric
`length_cm`	`int32`	Euclidean distance start → target, in cm (span events).	numeric
`x_target`	`int16`	Target x-coordinate in cm (corner-origin, same convention as top-level x/y).	numeric
`y_target`	`int16`	Target y-coordinate in cm (corner-origin, same convention as top-level x/y).	numeric

shot

Property	Type	Description	Values
`body_part`	`str`	Which body part contacted the ball. `unknown` is the engine-side placeholder for unmeasured rows.	`head`, `both_hands`, `unknown`
`confidence_detection`	`float32`	Detection confidence [0,1].	numeric
`confidence_event`	`float32`	Event [0,1]. Model confidence for this event class.	numeric
`confidence_identity`	`float32`	Identity confidence [0,1]. Null for non-actor events and for rows where the jersey/player_id was not resolved (team-only actor rows have this null).	numeric

tackle

Property	Type	Description	Values
`body_part`	`str`	Which body part contacted the ball. `unknown` is the engine-side placeholder for unmeasured rows.	`head`, `both_hands`, `unknown`
`confidence_detection`	`float32`	Detection confidence [0,1].	numeric
`confidence_event`	`float32`	Event [0,1]. Model confidence for this event class.	numeric
`confidence_identity`	`float32`	Identity confidence [0,1]. Null for non-actor events and for rows where the jersey/player_id was not resolved (team-only actor rows have this null).	numeric

block

Property	Type	Description	Values
`body_part`	`str`	Which body part contacted the ball. `unknown` is the engine-side placeholder for unmeasured rows.	`head`, `both_hands`, `unknown`
`confidence_detection`	`float32`	Detection confidence [0,1].	numeric
`confidence_event`	`float32`	Event [0,1]. Model confidence for this event class.	numeric
`confidence_identity`	`float32`	Identity confidence [0,1]. Null for non-actor events and for rows where the jersey/player_id was not resolved (team-only actor rows have this null).	numeric

team_possession

Property	Type	Description	Values
`team_label`	`int8`	Team label, harmonised across the match (0 or 1).	numeric
`team_side`	`str`	Camera-relative side a `team_possession` span belongs to.	`left`, `right`, `unknown`
`unknown_reason`	`str`	Why a span was tagged `team_side='unknown'`.	`unclear`

player_possession

Property	Type	Description	Values
`confidence_identity`	`float32`	Identity confidence [0,1]. Null for non-actor events and for rows where the jersey/player_id was not resolved (team-only actor rows have this null).	numeric
`model_source`	`str`	Player-possession source: which model produced the span (`short` / `long` / `mix`).	`short`, `long`, `mix`

ball_phase

Property	Type	Description	Values
`phase`	`str`	Ball-phase span label.	`in_play`, `out_of_bounds`, `in_bounds_stoppage`, `half_kickoff`

ball_pitchzone

Property	Type	Description	Values
`pitchzone`	`str`	Pitch-third span label on `ball_pitchzone` events.	`defensive_third`, `middle_third`, `attacking_third`

scene

Property	Type	Description	Values
`is_analysable`	`bool`	Whether this scene is the main-camera broadcast feed.	numeric

match_timeline

Property	Type	Description	Values
`period`	`str`	Match-period span label. Engine currently emits only `full_game`.	`full_game`

Metadata Field Reference

Full details for all enumerated metadata fields across event types.

`body_part`

Which body part contacted the ball.

Value	Description
`head`	Headed contact. Includes header, flick-on, headed pass, headed clearance.
`both_hands`	Two-handed throw. Used for throw-in restarts (paired with `set_piece=throw_in`).
`unknown`	Engine-side placeholder for rows where body part was not measured. Distinct from a positive identification of a non-standard body part.

`model_source`

Which player-possession model produced the span. Exposed so downstream consumers can slice quality metrics by model: the two horizons have different precision and recall trade-offs, and mix is informative in its own right (it correlates with handoff regions). Adding new values is purely additive.

Value	Description
`short`	Span produced by the short-horizon player-possession model.
`long`	Span produced by the long-horizon player-possession model.
`mix`	Blended source within the span. Both models contributed.

`pass_type`

Stylistic flavour of a pass event. Null for plain passes. Only set when a positive style signal fires.

Value	Description
`cross`	Wide delivery into the box. Set independently of `set_piece` and `body_part` (e.g. an open-play headed cross is `set_piece=open_play`, `pass_type=cross`, `body_part=head`).

`period`

Match-period span label on match_timeline events.

Value	Description
`full_game`	A single span covering the entire match. Engine currently emits this and only this.

`phase`

Ball-phase span label on ball_phase events.

Value	Description
`in_play`	Active gameplay. The ball is in bounds and the referee has not stopped play.
`out_of_bounds`	Between the ball crossing a touchline or goal-line and the restart.
`in_bounds_stoppage`	Play is paused but the ball is still on-pitch (e.g. foul, injury). Distinct from `out_of_bounds`.
`half_kickoff`	Single-frame kickoff anchor at the start of a period.

`pitchzone`

Pitch-third span label on ball_pitchzone events.

Value	Description
`defensive_third`	Ball is in the longitudinal third closest to the in-possession team's own goal.
`middle_third`	Ball is in the central longitudinal third.
`attacking_third`	Ball is in the longitudinal third closest to the opposition goal.

`set_piece`

Restart context for a pass event. Records how the pass entered play.

Value	Description
`open_play`	In-play default. Always set on `pass` rows (not omitted) so consumers can distinguish "in play" from "field not declared".
`throw_in`	Two-handed touchline restart after the ball leaves the sideline. Pair with `body_part=both_hands`.
`kick_off`	Centre-circle restart at the start of a half or after a goal. Single-frame anchor.
`corner_kick`	Restart from the corner arc after the defending team puts the ball over its own goal line.
`free_kick`	Restart awarded after a foul or other in-play stoppage, taken from the spot of the offence.
`goal_kick`	Restart from the six-yard box after the attacking team puts the ball over the byline.

`team_side`

Camera-relative side a team_possession span belongs to.

Value	Description
`left`	Camera-relative left side of the pitch.
`right`	Camera-relative right side of the pitch.
`unknown`	Possession classifier had low confidence. Pair with `metadata.unknown_reason` for the cause.

`unknown_reason`

Why a span was tagged unknown (currently only set on team_possession spans with team_side='unknown').

Value	Description
`unclear`	Possession classifier confidence was below threshold.

Basic Examples

All throw-ins

{
  "filters": [
    {
      "type": "event_property",
      "event_type": "pass",
      "properties": [
        { "field": "set_piece", "eq": "throw_in" }
      ]
    }
  ]
}

All crosses

{
  "filters": [
    {
      "type": "event_property",
      "event_type": "pass",
      "properties": [
        { "field": "pass_type", "eq": "cross" }
      ]
    }
  ]
}

All tackles

{
  "filters": [
    {
      "type": "event_property",
      "event_type": "tackle",
      "properties": []
    }
  ]
}

Long passes (20+ metres)

{
  "filters": [
    {
      "type": "event_property",
      "event_type": "pass",
      "properties": [
        { "field": "length_cm", "gte": 2000 }
      ]
    }
  ]
}

Combining Constraints

Headed passes from restarts

{
  "filters": [
    {
      "type": "event_property",
      "event_type": "pass",
      "properties": [
        { "field": "body_part", "eq": "head" },
        { "field": "set_piece", "in_": ["throw_in", "kick_off"] }
      ]
    }
  ]
}

Long open-play crosses by a team

{
  "filters": [
    {
      "type": "event_property",
      "event_type": "pass",
      "properties": [
        { "field": "set_piece", "eq": "open_play" },
        { "field": "pass_type", "eq": "cross" },
        { "field": "length_cm", "gte": 2500 }
      ],
      "teams": ["team_0"]
    }
  ]
}

Filtering by Player or Team

Shots by a specific player

{
  "filters": [
    {
      "type": "event_property",
      "event_type": "shot",
      "properties": [],
      "players": ["0-10"]
    }
  ]
}

Tackles by Team 1

{
  "filters": [
    {
      "type": "event_property",
      "event_type": "tackle",
      "properties": [],
      "teams": ["team_1"]
    }
  ]
}

Combining with Other Filters

Throw-ins in the second half

{
  "operator": "AND",
  "filters": [
    {
      "type": "event_property",
      "event_type": "pass",
      "properties": [
        { "field": "set_piece", "eq": "throw_in" }
      ]
    },
    { "type": "match_timeline", "periods": ["second_half"] }
  ]
}

Tackles in the defensive third

{
  "operator": "AND",
  "filters": [
    {
      "type": "event_property",
      "event_type": "tackle",
      "properties": [],
      "teams": ["team_0"]
    },
    { "type": "ball_location", "x_min": 0, "x_max": 35 }
  ]
}

Response Structure

Event property intervals include player and team fields when the event has an actor:

{
  "start": 125.5,
  "end": 135.5,
  "label": "pass",
  "type": "event_property",
  "player_id": "0-10",
  "team_id": "team_0",
  "team_name": "Home Team"
}

Response Fields

Field	Type	Description
`start`	float	Start time in seconds
`end`	float	End time in seconds
`label`	string	Event type, or `"event_type: value"` for single-constraint queries
`type`	string	Always `"event_property"`
`player_id`	string \| null	Player ID if the event has an actor
`team_id`	string \| null	Team identifier
`team_name`	string \| null	Team display name