Get live match timeline - TheStatsAPI

GET

/

football

/

matches

/

{match_id}

/

live-timeline

Get live match timeline

curl --request GET \
  --url https://api.thestatsapi.com/api/football/matches/{match_id}/live-timeline \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.thestatsapi.com/api/football/matches/{match_id}/live-timeline', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.thestatsapi.com/api/football/matches/{match_id}/live-timeline"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "data": {
    "match_id": "mt_838955483",
    "coverage": "full",
    "events": [
      {
        "sequence": 3,
        "minute": 45,
        "extra_time": 3,
        "period": "first_half",
        "type": "yellow_card",
        "team": {
          "id": "tm_1002",
          "name": "Aston Villa",
          "slug": "aston-villa-tm_1002"
        },
        "player": {
          "id": "pl_61849099",
          "name": "Ollie Watkins",
          "slug": "ollie-watkins-pl_61849099"
        }
      }
    ]
  },
  "meta": {
    "total": 10,
    "coverage": "full",
    "last_updated": "2026-05-15T21:05:49.659Z",
    "match_status": "live"
  }
}

After full-time, use Get match timeline. How to poll during a match: Live matches.

Authorizations

Authorization

string

header

required

Your API key, sent as Authorization: Bearer YOUR_API_KEY. Get one at https://www.thestatsapi.com/api-keys

Path Parameters

match_id

string

required

Match ID of a live match. Find live matches with GET /football/matches?status=live

Query Parameters

event_type

string

Comma-separated event types to keep (values of type, e.g. goal, yellow_card, substitution). Defaults to all. Unknown values return 400. Penalty goals are penalty_scored, not goal, so use goal,penalty_scored to get every goal; shoot-out kicks are also penalty_scored with period penalties

period

string

Comma-separated periods to keep. Values are first_half, second_half, extra_time_first_half, extra_time_second_half and penalties

team_id

string

Only events for this team

Response

The live timeline.

data

object

required

Show child attributes

meta

object

required

Show child attributes

Example:

{
  "total": 10,
  "coverage": "full",
  "last_updated": "2026-05-15T21:05:49.659Z",
  "match_status": "live"
}

Get live match timeline

curl --request GET \
  --url https://api.thestatsapi.com/api/football/matches/{match_id}/live-timeline \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.thestatsapi.com/api/football/matches/{match_id}/live-timeline', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.thestatsapi.com/api/football/matches/{match_id}/live-timeline"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "data": {
    "match_id": "mt_838955483",
    "coverage": "full",
    "events": [
      {
        "sequence": 3,
        "minute": 45,
        "extra_time": 3,
        "period": "first_half",
        "type": "yellow_card",
        "team": {
          "id": "tm_1002",
          "name": "Aston Villa",
          "slug": "aston-villa-tm_1002"
        },
        "player": {
          "id": "pl_61849099",
          "name": "Ollie Watkins",
          "slug": "ollie-watkins-pl_61849099"
        }
      }
    ]
  },
  "meta": {
    "total": 10,
    "coverage": "full",
    "last_updated": "2026-05-15T21:05:49.659Z",
    "match_status": "live"
  }
}