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`

goal

Property	Type	Description	Values
`confidence_event`	`float32`	Event [0,1]. Model confidence for this event class.	numeric

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`

A span covering the regulation match period. The engine currently emits a single period=full_game row per match, anchoring every other event to match-time rather than wall-clock or frame numbers. First/second-half boundaries are reserved in the period enum but not detected today.

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

`phase`

A continuous span describing whether the ball is in play, out of bounds, or in a stoppage. Carries a phase enum: in_play, out_of_bounds, in_bounds_stoppage, half_kickoff.

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`

A continuous span describing which longitudinal third of the pitch the ball is currently in. Carries a pitchzone enum: defensive_third, middle_third, attacking_third.

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`

A continuous span over which one team is in possession of the ball. Ends when possession transfers to the opponent, the ball goes out of play, or the underlying classifier loses confidence (team_side = 'unknown').

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