> ## Documentation Index
> Fetch the complete documentation index at: https://www.thestatsapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /football/matches/{match_id}/timeline

> Return a chronological event timeline for goals, shots, cards, substitutions, VAR, periods, and other match events.

Return the event-by-event timeline for a single match.

## Endpoint

```text theme={null}
GET https://api.thestatsapi.com/api/football/matches/{match_id}/timeline
```

Events are sorted in true match order. Stoppage time is preserved as `minute` plus `extra_time`, so `45+3` is returned as `{ "minute": 45, "extra_time": 3 }`.

## Path parameters

| Name       | Type   | Required | Description                       |
| ---------- | ------ | -------- | --------------------------------- |
| `match_id` | string | Yes      | Match ID. Example: `mt_838955483` |

## Query parameters

| Name         | Type   | Required | Description                                                                                                           |
| ------------ | ------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `event_type` | string | No       | Comma-separated event types. Example: `goal,yellow_card,foul`                                                         |
| `period`     | string | No       | Comma-separated periods: `first_half`, `second_half`, `extra_time_first_half`, `extra_time_second_half`, `penalties`. |
| `team_id`    | string | No       | Filter to events involving a single team. Example: `tm_0406`                                                          |

## Response

```json theme={null}
{
  "data": {
    "match_id": "mt_838955483",
    "coverage": "full",
    "events": [
      {
        "sequence": 8,
        "minute": 45,
        "extra_time": 3,
        "period": "first_half",
        "type": "goal",
        "team": {
          "id": "tm_1002",
          "name": "Newcastle United",
          "slug": "newcastle-united"
        },
        "player": {
          "id": "pl_4016958",
          "name": "Alexander Isak",
          "slug": "alexander-isak"
        }
      }
    ]
  },
  "meta": {
    "total": 312,
    "coverage": "full"
  }
}
```

## Empty coverage

When a timeline is not available, the endpoint returns `200` with an empty `events` array and `meta.coverage = "none"`. The `reason` can be `match_not_started`, `no_events`, or `not_supported`. A `404` is only returned when the match itself does not exist.