GET /football/matches/{match_id}/timeline - The Stats API

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

Endpoint

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

{
  "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.