Build live scores and in-play stats

Use this page to show scores, stats and events while matches are being played.

Fastest way: ask your AI. Set up your coding tool once with Build with AI, then paste:

Prompt

Using TheStatsAPI (reference: https://api.thestatsapi.com/llms.txt), build a live scores page: a server route lists matches with status=live, and for a selected match polls /live-stats every 30 seconds until it stops being live. Keep the API key server-side.

How live data works

There are no webhooks, WebSockets or push messages. You poll: ask for live matches, then call the live endpoints for the matches you show.

You want	Call
Which matches are live, with the clock	`GET /football/matches?status=live`
Score and team stats	`GET /football/matches/{match_id}/live-stats`
Goals, cards, substitutions and other events	`GET /football/matches/{match_id}/live-timeline`
Per-player stats	`GET /football/matches/{match_id}/live-player-stats`
In-play odds	`GET /football/matches/{match_id}/odds/live` (see Odds)

The JavaScript examples run on your server and read your key from the THESTATSAPI_API_KEY environment variable. The match IDs below were live when this page was written; use one that is live when you try it.

1. Find live matches

curl "https://api.thestatsapi.com/api/football/matches?status=live" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/matches?status=live",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const { data } = await res.json();
for (const m of data) {
  const minute = m.live?.elapsed_minutes ?? "-";
  console.log(`${minute}' ${m.home_team.name} ${m.score.home}-${m.score.away} ${m.away_team.name}`);
}

Response (one match, trimmed):

Response

{
  "data": [
    {
      "id": "mt_899703080",
      "competition_id": "comp_8321",
      "status": "live",
      "utc_date": "2026-10-09T19:00:00.000Z",
      "home_team": { "id": "tm_3809", "name": "West Ham United" },
      "away_team": { "id": "tm_2949", "name": "Queens Park Rangers" },
      "score": { "home": 0, "away": 1 },
      "live": {
        "match_status": "first_half",
        "elapsed_minutes": 29,
        "period": "first_half",
        "updated_at": "2026-10-09T19:29:14.093Z"
      },
      "live_odds_available": true
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 45, "total_pages": 3 }
}

live is null unless status is live. Just after kickoff, every field inside live can be null until the first clock update arrives. On a busy evening there can be dozens of live matches, so add per_page=100, or filter with competition_id or team_id to watch only the matches you care about.

2. Poll live stats

curl "https://api.thestatsapi.com/api/football/matches/mt_899703080/live-stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

const headers = { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` };
const url = "https://api.thestatsapi.com/api/football/matches/mt_899703080/live-stats";

async function poll() {
  const res = await fetch(url, { headers });
  if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") ?? 60);
    return setTimeout(poll, wait * 1000);
  }
  if (!res.ok) return; // 409: the match isn't live (any more). Use /stats for final totals
  const { data } = await res.json();
  console.log(data.meta.elapsed_minutes, data.meta.home_goals, data.meta.away_goals);
  if (data.meta.match_status === "finished") return;
  setTimeout(poll, 30_000);
}
poll();

Response (trimmed):

Response

{
  "data": {
    "match_id": "mt_899703080",
    "meta": {
      "match_status": "first_half",
      "elapsed_minutes": 29,
      "home_goals": 0,
      "away_goals": 1,
      "period": "first_half"
    },
    "stats": {
      "ball_possession": { "all": { "home": 55, "away": 45 } },
      "total_shots": { "all": { "home": 1, "away": 2 } },
      "shots_on_target": { "all": { "home": 0, "away": 1 } },
      "expected_goals": { "all": { "home": 0.06, "away": 0.85 } }
    }
  }
}

Which stats appear depends on the match. Check that a key exists before you read it.

3. Poll the live timeline

Filter with event_type (e.g. goal, penalty_scored, yellow_card, substitution), period or team_id.

Penalty goals are penalty_scored events, not goal. To get every goal, ask for both: event_type=goal,penalty_scored. Penalty shoot-out kicks are also penalty_scored, with "period": "penalties", so leave those out when you count match goals.

curl "https://api.thestatsapi.com/api/football/matches/mt_899703080/live-timeline?event_type=goal,penalty_scored,yellow_card" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/matches/mt_899703080/live-timeline?event_type=goal,penalty_scored,yellow_card",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const { data, meta } = await res.json();
for (const e of data.events) console.log(`${e.minute}' ${e.type} ${e.player?.name ?? ""}`);

Response (trimmed):

Response

{
  "data": {
    "match_id": "mt_899703080",
    "coverage": "full",
    "events": [
      {
        "sequence": 1,
        "minute": 17,
        "extra_time": 0,
        "period": "first_half",
        "type": "yellow_card",
        "team": { "id": "tm_3809", "name": "West Ham United" },
        "player": { "id": "pl_30432621", "name": "Arne Engels" }
      },
      {
        "sequence": 2,
        "minute": 18,
        "extra_time": 0,
        "period": "first_half",
        "type": "penalty_scored",
        "team": { "id": "tm_2949", "name": "Queens Park Rangers" },
        "player": { "id": "pl_61568182", "name": "Nicolas Madsen" }
      }
    ]
  },
  "meta": {
    "total": 6,
    "coverage": "full",
    "last_updated": "2026-10-09T20:30:03.372Z",
    "match_status": "live"
  }
}

Stoppage time is kept separate: 45+3’ comes back as "minute": 45, "extra_time": 3.

4. Live player stats

/live-player-stats returns one entry per player with rating, minutes, passing, shooting (including xG), duels and defending. Touches, fouls and cards are under general. Add player_ids=pl_...,pl_... to get only some players.

curl "https://api.thestatsapi.com/api/football/matches/mt_899703080/live-player-stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/matches/mt_899703080/live-player-stats",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const { data, meta } = await res.json(); // meta.match_status === "live"

One entry (trimmed):

Response

{
  "player_id": "pl_45450148",
  "player_name": "Ronnie Edwards",
  "team_id": "tm_2949",
  "position": "M",
  "rating": 6.84,
  "started": true,
  "minutes_played": 25,
  "passing": { "total_passes": 7, "accurate_passes": 7, "key_passes": 0 },
  "shooting": { "goals": 0, "total_shots": 0, "expected_assists": 0.01 }
}

How often to poll

Every 30 seconds is enough. Live stats responses can be cached for up to 30 seconds, so polling faster doesn’t get you fresher data.
Only poll matches that are live and on screen. Every call counts against your rate limits and quota.
On 429, wait the number of seconds in the Retry-After header before trying again.
Refresh the live match list every minute or two to pick up kickoffs and full-time whistles.

Before kickoff and after full time

Endpoint	Before kickoff	While live	After full time
`/live-stats`	`409`	`200`	`200` with `meta.match_status: "finished"` for up to 5 minutes, then `409`
`/live-timeline`, `/live-player-stats`	`409`	`200`	`409`
`/odds/live`	`404`	`200` when `live_odds_available` is `true`	`404` (“Match is already completed”)
`/stats`, `/player-stats`, `/timeline`	No data yet: `/stats` and `/player-stats` return `404`, `/timeline` returns an empty `events` list	`409` (code `MATCH_IS_LIVE` on `/stats`)	`200` once the stats are in

The 409 for a match that isn’t live looks like this:

{ "error": { "code": "CONFLICT", "message": "Match is not live", "status_code": 409 } }

When you get it after a match, switch to the post-match endpoints: match stats, player stats and timeline.

Lineups come before kickoff: Get match lineups returns a predicted XI, then the official team sheet once it’s announced (about an hour before kickoff). Check type and confirmed to know which you have.

Get started

Guides

Core concepts

Build live scores and in-play stats

How live data works

1. Find live matches

2. Poll live stats

3. Poll the live timeline

4. Live player stats

How often to poll

Before kickoff and after full time

API reference

​How live data works

​1. Find live matches

​2. Poll live stats

​3. Poll the live timeline

​4. Live player stats

​How often to poll

​Before kickoff and after full time

​API reference

How live data works

1. Find live matches

2. Poll live stats

3. Poll the live timeline

4. Live player stats

How often to poll

Before kickoff and after full time

API reference