> 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 #### Common event types at a glance Use `type_id` to identify goals, cards and substitutions. These values were checked against the types API on 15 October 2026. All eight types have `model_type: event`. | type\_id | Name | code | developer\_name | | -------- | --------------- | --------------- | --------------- | | 14 | Goal | goal | GOAL | | 15 | Own Goal | owngoal | OWNGOAL | | 16 | Penalty | penalty | PENALTY | | 17 | Missed Penalty | missed\_penalty | MISSED\_PENALTY | | 19 | Yellowcard | yellowcard | YELLOWCARD | | 20 | Redcard | redcard | REDCARD | | 21 | Yellow/Red card | yellowredcard | YELLOWREDCARD | | 18 | Substitution | substitution | SUBSTITUTION | For VAR, distinguish the broad event `type_id` from its `sub_type_id`. Include `events.type;events.subType` to retrieve both classifications; treat `info` and `addition` as display context. 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" %} Retrieve the catalogue with GET . Follow pagination.next\_page until pagination.has\_more is false, using your API token on each request. Check the returned pagination.per\_page rather than assuming a requested page size was applied. Filter the complete collection locally for model\_type values event and sub\_event, then cache the IDs and names for lookup. {% 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 | For card events, true means the referee rescinded the card and false means the card still counts. For other events, or historical cards without this information, the value is null. Do not infer a goal-review lifecycle from this field. See the 2025-06-30 changelog entry. | | `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" %} In the previously checked fixture 19606962, the final response contained a VAR event with type\_id: 10 and sub\_type\_id: 1512 (Goal Disallowed). This demonstrates one returned classification, not the complete sequence of changes during the review. Handle VAR events alongside goals and use the latest fixture response; do not infer that a Goal event can never be updated or that rescinded will always have one particular value. {% 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" %} The full types catalogue checked on 15 October 2026 lists VAR (type\_id: 10) and VAR\_CARD (type\_id: 1697) as event types, and the review and decision labels above as sub\_event types. It does not list GOAL\_UNDER\_REVIEW, GOAL\_CONFIRMED or PENALTY\_DISALLOWED as event or sub-event types. Use REVIEW (9704), GOAL\_AWARDED (9703), GOAL\_DISALLOWED (1512), PENALTY\_CONFIRMED (9698) and PENALTY\_CANCELLED (9699) where returned. The catalogue defines classifications; it does not establish a guaranteed review sequence, whether the same event ID changes during a review, or fixed info/addition values. Check the latest fixture response rather than assuming a lifecycle from these names. {% 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` 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 what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.