Get started with The Stats API

This guide walks through the first requests most integrations need: verify connectivity, list competitions, list matches, and fetch details for one match.

Get your API key

Create an API key in your account dashboard and store it in an environment variable.

export STATS_API_KEY="YOUR_API_KEY"

Check API health

The health endpoint is public and does not require authentication.

curl --request GET \
  --url https://api.thestatsapi.com/api/health

A healthy API returns JSON like this:

{
  "status": "healthy",
  "timestamp": "2026-04-20T10:00:00Z"
}

Fetch competitions

List competitions to find stable competition IDs such as comp_3039.

curl --request GET \
  --url "https://api.thestatsapi.com/api/football/competitions?per_page=20" \
  --header "Authorization: Bearer $STATS_API_KEY"

import os
import requests

response = requests.get(
    "https://api.thestatsapi.com/api/football/competitions",
    headers={"Authorization": f"Bearer {os.environ['STATS_API_KEY']}"},
    params={"per_page": 20},
)

print(response.json())

const response = await fetch(
  "https://api.thestatsapi.com/api/football/competitions?per_page=20",
  {
    headers: {
      Authorization: `Bearer ${process.env.STATS_API_KEY}`,
    },
  }
);

console.log(await response.json());

Example response:

{
  "data": [
    {
      "id": "comp_3039",
      "name": "Premier League",
      "country": "England",
      "country_code": "GB",
      "subdivision_code": "GB-ENG",
      "confederation": null,
      "type": "league",
      "has_team_stats": true,
      "has_player_stats": true,
      "odds_available": true,
      "live_odds_available": true,
      "xg_available": true
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 48,
    "total_pages": 3
  }
}

Fetch matches

Query matches with date filters, competition/season filters, status, stage, or group.

curl --request GET \
  --url "https://api.thestatsapi.com/api/football/matches?competition_id=comp_3039&season_id=sn_6125938&date_from=2026-04-19&date_to=2026-04-20" \
  --header "Authorization: Bearer $STATS_API_KEY"

Match list responses include IDs such as mt_838955483 and flags such as xg_available, odds_available, and live_odds_available.

Fetch a match detail

Use the match ID from a list response to retrieve the full match record.

curl --request GET \
  --url https://api.thestatsapi.com/api/football/matches/mt_838955483 \
  --header "Authorization: Bearer $STATS_API_KEY"

import os
import requests

match_id = "mt_838955483"
response = requests.get(
    f"https://api.thestatsapi.com/api/football/matches/{match_id}",
    headers={"Authorization": f"Bearer {os.environ['STATS_API_KEY']}"},
)

print(response.json())

const matchId = "mt_838955483";
const response = await fetch(
  `https://api.thestatsapi.com/api/football/matches/${matchId}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.STATS_API_KEY}`,
    },
  }
);

console.log(await response.json());

After you have IDs, use the reference to fetch seasons, standings, squads, team/player stats, live stats, lineups, timelines, shotmaps, heatmaps, and odds.

Get Started

Core Concepts

Get started with The Stats API