Quickstart

Use this page to make your first requests: find the IDs you need, get a team’s next fixture and pull a league table. It takes about five minutes.

Fastest way: ask your AI. Set up your tool with Build with AI, then paste: “Read https://api.thestatsapi.com/llms.txt, then write a server-side script that prints Arsenal’s next fixture and the current Premier League table from TheStatsAPI. Read my key from the THESTATSAPI_API_KEY env var.”

To run the examples yourself: the JavaScript uses the built-in fetch in Node 18 or later (save it as a .mjs file so top-level await works), and the Python uses the requests package.

Get your API key

Create an account, then make a key on the API keys page. Copy it straight away: it’s only shown once.Save it as an environment variable so it stays out of your code:

export THESTATSAPI_API_KEY="YOUR_API_KEY"

Make your first request

Search competitions to find the Premier League’s ID.

curl "https://api.thestatsapi.com/api/football/competitions?search=Premier%20League&per_page=3" \
  -H "Authorization: Bearer $THESTATSAPI_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/competitions?search=Premier%20League&per_page=3",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const body = await res.json();
console.log(body.data[0].id); // comp_3039

import os
import requests

res = requests.get(
    "https://api.thestatsapi.com/api/football/competitions",
    params={"search": "Premier League", "per_page": 3},
    headers={"Authorization": f"Bearer {os.environ['THESTATSAPI_API_KEY']}"},
)
print(res.json()["data"][0]["id"])  # comp_3039

Response (trimmed):

{
  "data": [
    { "id": "comp_3039", "name": "Premier League", "country": "England", "type": "league", "xg_available": true },
    { "id": "comp_84287", "name": "Egyptian Premier League", "country": "Egypt", "type": "league", "xg_available": true },
    { "id": "comp_5824", "name": "Russian Premier League", "country": "Russia", "type": "league", "xg_available": true }
  ],
  "meta": { "page": 1, "per_page": 3, "total": 6, "total_pages": 2 }
}

The best match comes first, so comp_3039 is the Premier League. Lists always return data plus a meta object for pagination.

Find a team ID

Search teams the same way. Add is_mens_team=true to leave out women’s teams.

curl "https://api.thestatsapi.com/api/football/teams?search=Arsenal&is_mens_team=true&per_page=3" \
  -H "Authorization: Bearer $THESTATSAPI_API_KEY"

const res = await fetch(
  "https://api.thestatsapi.com/api/football/teams?search=Arsenal&is_mens_team=true&per_page=3",
  { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
);
const { data } = await res.json();
console.log(data.map((team) => `${team.id} ${team.name}`));

import os
import requests

res = requests.get(
    "https://api.thestatsapi.com/api/football/teams",
    params={"search": "Arsenal", "is_mens_team": "true", "per_page": 3},
    headers={"Authorization": f"Bearer {os.environ['THESTATSAPI_API_KEY']}"},
)
for team in res.json()["data"]:
    print(team["id"], team["name"])

Response (trimmed):

{
  "data": [
    { "id": "tm_9145", "name": "Arsenal", "country": "England", "is_mens_team": true },
    { "id": "tm_033813", "name": "Arsenal U21", "country": "England", "is_mens_team": true },
    { "id": "tm_270010", "name": "Arsenal Tula", "country": "Russian Federation", "is_mens_team": true }
  ],
  "meta": { "page": 1, "per_page": 3, "total": 13, "total_pages": 5 }
}

tm_9145 is Arsenal’s first team. You can also look up IDs in the ID finder in your dashboard. More in Finding IDs.

Get the team's next fixture

/football/matches returns the newest kickoff first. Add sort=utc_date to get the soonest first, so the first scheduled match is the next one.

curl "https://api.thestatsapi.com/api/football/matches?team_id=tm_9145&status=scheduled&sort=utc_date&per_page=1" \
  -H "Authorization: Bearer $THESTATSAPI_API_KEY"

const params = new URLSearchParams({
  team_id: "tm_9145",
  status: "scheduled",
  sort: "utc_date",
  per_page: "1",
});
const res = await fetch(`https://api.thestatsapi.com/api/football/matches?${params}`, {
  headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` },
});
const { data } = await res.json();
const next = data[0];
console.log(`${next.home_team.name} v ${next.away_team.name}, ${next.utc_date}`);

import os
import requests

res = requests.get(
    "https://api.thestatsapi.com/api/football/matches",
    params={"team_id": "tm_9145", "status": "scheduled", "sort": "utc_date", "per_page": 1},
    headers={"Authorization": f"Bearer {os.environ['THESTATSAPI_API_KEY']}"},
)
match = res.json()["data"][0]
print(match["home_team"]["name"], "v", match["away_team"]["name"], match["utc_date"])

Example response (trimmed):

{
  "data": [
    {
      "id": "mt_200199332",
      "competition_id": "comp_3039",
      "season_id": "sn_8406098",
      "matchday": 6,
      "status": "scheduled",
      "utc_date": "2026-10-10T11:30:00.000Z",
      "home_team": { "id": "tm_9145", "name": "Arsenal" },
      "away_team": { "id": "tm_0256", "name": "Leeds United" },
      "odds_available": true,
      "xg_available": false
    }
  ],
  "meta": { "page": 1, "per_page": 1, "total": 9, "total_pages": 9 }
}

utc_date is always UTC. For a team’s latest result, use status=finished and leave out sort. More in Fixtures and results.

Get the league table

Standings belong to a season. First get the competition’s current_season_id, then ask for that season’s table.

# 1. Current season ID
curl "https://api.thestatsapi.com/api/football/competitions/comp_3039" \
  -H "Authorization: Bearer $THESTATSAPI_API_KEY"

# 2. Standings for that season
curl "https://api.thestatsapi.com/api/football/competitions/comp_3039/seasons/sn_8406098/standings" \
  -H "Authorization: Bearer $THESTATSAPI_API_KEY"

const base = "https://api.thestatsapi.com/api";
const headers = { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` };

const comp = await fetch(`${base}/football/competitions/comp_3039`, { headers }).then((r) => r.json());
const seasonId = comp.data.current_season_id; // sn_8406098

const table = await fetch(
  `${base}/football/competitions/comp_3039/seasons/${seasonId}/standings`,
  { headers }
).then((r) => r.json());

for (const row of table.data) {
  console.log(row.position, row.team.name, row.points);
}

import os
import requests

base = "https://api.thestatsapi.com/api"
headers = {"Authorization": f"Bearer {os.environ['THESTATSAPI_API_KEY']}"}

comp = requests.get(f"{base}/football/competitions/comp_3039", headers=headers).json()
season_id = comp["data"]["current_season_id"]  # sn_8406098

table = requests.get(
    f"{base}/football/competitions/comp_3039/seasons/{season_id}/standings",
    headers=headers,
).json()

for row in table["data"]:
    print(row["position"], row["team"]["name"], row["points"])

Example standings response (trimmed; your numbers will differ):

{
  "data": [
    {
      "team": { "id": "tm_3039", "name": "Manchester City" },
      "position": 1,
      "matches_played": 5,
      "wins": 5,
      "draws": 0,
      "losses": 0,
      "goals_for": 13,
      "goals_against": 5,
      "goal_difference": 8,
      "points": 15,
      "group_label": null
    },
    {
      "team": { "id": "tm_9145", "name": "Arsenal" },
      "position": 2,
      "matches_played": 5,
      "wins": 4,
      "draws": 0,
      "losses": 1,
      "goals_for": 8,
      "goals_against": 4,
      "goal_difference": 4,
      "points": 12,
      "group_label": null
    }
  ]
}

Common mistakes

Mistake	What happens	Fix
Using `date=2026-10-10`	`400 UNKNOWN_PARAMETER`: “did you mean ‘date_from’ or ‘date_to’?”	Set `date_from` and `date_to` to the same day.
Leaving out `sort=utc_date` for upcoming fixtures	The first row is the scheduled match furthest in the future	Add `sort=utc_date`.
Sending `bearer` (lowercase) or no space after `Bearer`	`401 UNAUTHORIZED`	Send exactly `Authorization: Bearer YOUR_API_KEY`.
Guessing IDs	`404 NOT_FOUND`, `400 BAD_REQUEST` (“Invalid team_id”) or data for the wrong team	Look IDs up with `search=`, as above.

Next steps

Build with AI

Let Claude Code, Codex, Cursor or Lovable write the rest for you.

Finding IDs

Look up competitions, seasons, teams, players and matches.

Live matches

Show live scores and stats by polling during a match.

API reference

Every endpoint, parameter and response field.

Get started

Guides

Core concepts

Common mistakes

Next steps

Build with AI

Finding IDs

Live matches

API reference