Matches

List matches

Returns fixtures and results, 20 per page. Combine filters to get a team’s next match, a matchday, or every match between two dates.

Order: newest kickoff first by default (sort=-utc_date). Use sort=utc_date for soonest first.

Examples

Next fixture for a team (first row is the next match): GET /football/matches?team_id=tm_9145&status=scheduled&sort=utc_date&per_page=1
Latest result for a team: GET /football/matches?team_id=tm_9145&status=finished&per_page=1
One day’s Premier League matches: GET /football/matches?competition_id=comp_3039&date_from=2026-10-10&date_to=2026-10-10&sort=utc_date
One matchday: GET /football/matches?competition_id=comp_3039&season_id=sn_8406098&matchday=6

There is no date parameter. For a single day, set date_from and date_to to the same date.

GET

football

matches

List matches

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

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

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

{
  "data": [
    {
      "id": "mt_838955483",
      "competition_id": "comp_3039",
      "season_id": "sn_6125938",
      "matchday": 37,
      "stage": "regular",
      "stage_name": null,
      "status": "finished",
      "utc_date": "2026-05-15T19:00:00.000Z",
      "home_team": {
        "id": "tm_1002",
        "name": "Aston Villa"
      },
      "away_team": {
        "id": "tm_0406",
        "name": "Liverpool"
      },
      "score": {
        "home": 4,
        "away": 2,
        "final_score": null,
        "regulation": {
          "home": 4,
          "away": 2
        },
        "after_extra_time": null,
        "penalty_shootout": null,
        "went_to_extra_time": false,
        "went_to_penalties": false,
        "winner": "home"
      },
      "group_label": null,
      "is_neutral": false,
      "live": null,
      "home_manager": {
        "id": "mgr_990303",
        "name": "Unai Emery"
      },
      "away_manager": {
        "id": "mgr_96180711",
        "name": "Arne Slot"
      },
      "odds_available": true,
      "live_odds_available": false,
      "xg_available": true,
      "shotmap_available": true,
      "xg_quality": "full"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

Start here to get the match_id that every other match endpoint needs. Recipes with code: Fixtures and results.

Authorizations

Authorization

string

header

required

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

Query Parameters

page

integer

default:1

Page number, starting at 1. meta.total_pages tells you how many there are

Required range: x >= 1

per_page

integer

default:20

Results per page (default 20, max 100). The older name limit also works the same way

Required range: 1 <= x <= 100

competition_id

string

Only matches in this competition

season_id

string

Only matches in this season. If you also send competition_id, the season must belong to it or you get 400 SEASON_COMPETITION_MISMATCH

team_id

string

Only matches this team plays in, home or away

date_from

string<date>

Kickoff on or after this date, YYYY-MM-DD. Days are read in the utc_offset time zone (UTC by default)

date_to

string<date>

Kickoff on or before the end of this date, YYYY-MM-DD. Must not be earlier than date_from

utc_offset

string

default:+00:00

Time zone offset for reading date_from and date_to, as +HH:MM or -HH:MM (hours up to 14). Defaults to +00:00 (UTC). Kickoff times in the response are always UTC

Pattern: ^[+-](?:0?\d|1[0-4]):[0-5]\d$

matchday

integer

Round number in a league season (positive integer)

Required range: x >= 1

status

enum<string>

Match status

Available options:

scheduled,

live,

finished,

postponed,

cancelled

stage

enum<string>

default:all

regular returns league and group-stage matches only. playoff returns knockout and play-off matches only (for example Champions League knockout rounds or Championship play-offs). all (default) returns both

Available options:

regular,

playoff,

all

group

enum<string>

Group letter A to L (case-insensitive) for tournaments with a group stage, such as the FIFA World Cup. Requires competition_id; without it you get 400

Available options:

A,

B,

C,

D,

E,

F,

G,

H,

I,

J,

K,

L

sort

enum<string>

default:-utc_date

Kickoff order. -utc_date (default) is newest first. utc_date is soonest first; use it with status=scheduled for upcoming fixtures. Matches with the same kickoff are ordered by match ID, so pages are stable

Available options:

-utc_date,

utc_date

Response

A page of matches.

data

object[]

Show child attributes

meta

object

Show child attributes

List matches

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

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

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

{
  "data": [
    {
      "id": "mt_838955483",
      "competition_id": "comp_3039",
      "season_id": "sn_6125938",
      "matchday": 37,
      "stage": "regular",
      "stage_name": null,
      "status": "finished",
      "utc_date": "2026-05-15T19:00:00.000Z",
      "home_team": {
        "id": "tm_1002",
        "name": "Aston Villa"
      },
      "away_team": {
        "id": "tm_0406",
        "name": "Liverpool"
      },
      "score": {
        "home": 4,
        "away": 2,
        "final_score": null,
        "regulation": {
          "home": 4,
          "away": 2
        },
        "after_extra_time": null,
        "penalty_shootout": null,
        "went_to_extra_time": false,
        "went_to_penalties": false,
        "winner": "home"
      },
      "group_label": null,
      "is_neutral": false,
      "live": null,
      "home_manager": {
        "id": "mgr_990303",
        "name": "Unai Emery"
      },
      "away_manager": {
        "id": "mgr_96180711",
        "name": "Arne Slot"
      },
      "odds_available": true,
      "live_odds_available": false,
      "xg_available": true,
      "shotmap_available": true,
      "xg_quality": "full"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

Overview

Competitions

Teams

Matches

Players

Odds

Coverage

List matches

Authorizations

Query Parameters

Response