> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/definitions/types/events.md). # Events ## Events, timeline & sub-event types This reference lists all event, timeline, and sub-event type IDs available across the Sportmonks Football API. Every event has a unique `type_id` identifying its broad category, and many events also carry a `sub_type_id` for more specific classification within that category. {% hint style="info" %} You can request all possible types with their unique id via the types endpoint: `https://api.sportmonks.com/v3/core/types?api_token=YOUR_TOKEN`. We recommend retrieving all types and storing them in your own database rather than resolving them live on every request. {% endhint %} ### The complete Event object schema Every entry in the `events` include shares this shape, regardless of `type_id`: | Field | Type | Description | | ------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | integer | Unique identifier for this event | | `fixture_id` | integer | The fixture this event belongs to | | `period_id` | integer | The period (half, extra time) this event occurred in | | `participant_id` | integer | The team this event is attributed to | | `type_id` | integer | The broad event category, see tables below | | `section` | string | Always `"event"` for the events include (`"timeline"` for the timeline include) | | `player_id` | integer | The primary player involved, null where not applicable | | `related_player_id` | integer | A secondary player involved (assist provider, player coming on/off), null if not applicable | | `player_name` / `related_player_name` | string | Display names for the above | | `result` | string | The score after this event, only populated on goal-type events | | `info` | string | Free-text context, varies by event type | | `addition` | string | Human-readable label, e.g. "1st Goal", "3rd Yellowcard" | | `minute` / `extra_minute` | integer | When the event occurred | | `injured` | boolean | Whether this substitution was injury-related | | `on_bench` | boolean | Whether the player was on the bench at the time | | `coach_id` | integer | Populated instead of `player_id` for coach-level events (e.g. a coach receiving a card) | | `sub_type_id` | integer | More specific classification, see the Sub-events table. Null if not applicable | | `detailed_period_id` | integer | The specific period sub-division this event occurred in | | `rescinded` | boolean/null | See the Corrections and disallowed events section. Observed values: `false` (confirmed standing) or `null` (not applicable). Never confirmed as `true` in testing to date | | `sort_order` | integer | Order within its type/period grouping | ### Assists are not a separate event type {% hint style="warning" %} There is no standalone "Assist" `type_id`. An assist is represented via the `related_player_id`/`related_player_name` fields on the **Goal** event (`type_id: 14`) itself, pointing to the player who provided the assist. Don't look for a dedicated assist event, it doesn't exist at the event level. (A separate `Assists` statistic, `type_id: 79`, exists under the Statistics types for aggregate counts.) {% endhint %} ### Events (`model_type: event`) | type\_id | Name | developer\_name | | -------- | --------------------- | ----------------------- | | 10 | VAR | VAR | | 14 | Goal | GOAL | | 15 | Own Goal | OWNGOAL | | 16 | Penalty | PENALTY | | 17 | Missed Penalty | MISSED\_PENALTY | | 18 | Substitution | SUBSTITUTION | | 19 | Yellowcard | YELLOWCARD | | 20 | Redcard | REDCARD | | 21 | Yellow/Red card | YELLOWREDCARD | | 22 | Penalty Shootout Miss | PENALTY\_SHOOTOUT\_MISS | | 23 | Penalty Shootout Goal | PENALTY\_SHOOTOUT\_GOAL | | 1675 | Highlight | HIGHLIGHT | | 1697 | VAR\_CARD | VAR\_CARD | {% hint style="warning" %} **A disallowed or overturned goal does not appear as a Goal event with a correction flag.** It appears as its own distinct combination: `type_id: 10` (VAR) with `sub_type_id: 1512` (Goal Disallowed). Confirmed via a live 2026 World Cup fixture. Do not expect a `type_id: 14` Goal event to be retroactively marked, listen for `type_id: 10` events instead. {% endhint %} ### Timeline (`model_type: timeline`) Returned via the `timeline` include, a curated subset of shot/set-piece events distinct from the main Events feed: | type\_id | Name | developer\_name | | -------- | --------------- | ----------------- | | 126 | Corner | CORNER | | 568 | Offside | OFFSIDE | | 569 | Shot On Target | SHOT\_ON\_TARGET | | 570 | Shot Off Target | SHOT\_OFF\_TARGET | ### Sub-events (`model_type: sub_event`) Resolve via the `events.subType` include, or by looking up `sub_type_id` against this table directly. #### Fouls & misconduct | sub\_type\_id | Name | developer\_name | | ------------- | -------------------------- | ----------------------------- | | 1495 | Roughing | ROUGHING | | 1496 | Foul | FOUL | | 1497 | Argument | ARGUMENT | | 1498 | Violent conduct | VIOLENT\_CONDUCT | | 1499 | Handball | HANDBALL | | 1500 | Dangerous play | DANGEROUS\_PLAY | | 1501 | Time wasting | TIME\_WASTING | | 1502 | Persistent fouling | PERSITENT\_FOULING | | 1503 | Simulation | SIMULATION | | 1504 | Entering field unallowed | ENTERING\_FIELD\_UNALLOWED | | 1505 | Professional last man foul | PROFESSIONAL\_LAST\_MAN\_FOUL | | 1506 | Off the ball foul | OFF\_THE\_BALL\_FOUL | | 1511 | Holding | HOLDING | | 1513 | Elbowing | ELBOWING | | 1515 | Diving | DIVING | | 1516 | Tripping | TRIPPING | | 1517 | Handling | HANDLING | | 1518 | Taking of shirt | TAKING\_OF\_SHIRT | | 5303 | Unsporting behaviour | UNSPORTING\_BEHAVIOUR | #### Shot & goal descriptors | sub\_type\_id | Name | developer\_name | | ------------- | ------------------ | -------------------- | | 1519 | Free Kick | FREE\_KICK | | 1520 | Long distance shot | LONG\_DISTANCE\_SHOT | | 1521 | Left foot shot | LEFT\_FOOT\_SHOT | | 1522 | Right foot shot | RIGHT\_FOOT\_SHOT | | 1510 | Hit the post | HIT\_THE\_POST | | 1694 | Header | HEADER | | 1695 | Shot | SHOT | | 1514 | Offside | OFFSIDE | #### Penalty outcomes | sub\_type\_id | Name | developer\_name | | ------------- | --------------------------- | ------------------------------ | | 1507 | Penalty Scored | PENALTY\_SCORED | | 1508 | Penalty shot off target | PENALTY\_SHOT\_OFF\_TARGET | | 1509 | Penalty saved by goalkeeper | PENALTY\_SAVED\_BY\_GOALKEEPER | | 9698 | Penalty confirmed | PENALTY\_CONFIRMED | | 9699 | Penalty cancelled | PENALTY\_CANCELLED | {% hint style="info" %} **"Penalty Save" is `sub_type_id: 1509`**, nested under `type_id: 17` (Missed Penalty), not its own top-level event type. Confirmed via live testing. {% endhint %} #### Substitutions | sub\_type\_id | Name | developer\_name | | ------------- | ------------------------------ | ------------------------ | | 1523 | Tactical sub | TACTICAL\_SUB | | 1524 | Substitution because of injury | SUB\_BECAUSE\_OF\_INJURY | | 1696 | Leaving Field | LEAVING\_FIELD | #### VAR reviews & corrections | sub\_type\_id | Name | developer\_name | | ------------- | ------------------ | -------------------- | | 9704 | Review | REVIEW | | 9703 | Goal awarded | GOAL\_AWARDED | | 1512 | Goal Disallowed | GOAL\_DISALLOWED | | 9701 | Card adjusted | CARD\_ADJUSTED | | 9702 | Red card cancelled | RED\_CARD\_CANCELLED | | 2127 | Card Withdrawn | CARD\_WITHDRAWN | {% hint style="success" %} **This confirms VAR corrections do have a multi-stage model**, just not the exact two-stage "under review → disallowed" flow an older blog post described. The actual mechanism uses distinct sub\_event outcomes (`Review`, `Goal awarded`, `Goal Disallowed`, `Card adjusted`, `Red card cancelled`, `Card Withdrawn`) attached to `type_id: 10` (VAR) or `type_id: 1697` (VAR\_CARD) events, rather than a single repeating event being edited in place. {% endhint %} ### Related pages * [Events include tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/events): concepts, nested includes, and worked examples * [Statistics Types Reference](https://docs.sportmonks.com/v3/definitions/types/statistics): for aggregate statistic type\_ids (including the `Assists` counter, `type_id: 79`) * [Periods include tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/periods): for `periods.statistics` and period-level breakdowns --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sportmonks.com/v3/definitions/types/events.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.