GET /football/matches — list and filter matches - The Stats API

List matches

Endpoint

GET https://api.thestatsapi.com/api/football/matches

Retrieve a paginated list of matches with optional filters. Use date/status filters to query past (e.g. finished) or upcoming fixtures.

Query parameters

Name	Type	Required	Default	Description
`page`	integer	No	`1`	Page number (default 1)
`per_page`	integer	No	`20`	Results per page (default 20, max 100). The legacy alias `limit` is also accepted and behaves identically.
`competition_id`	string	No		Filter by competition (optional). Example: `comp_3039`
`season_id`	string	No		Filter by season (optional, requires competition_id). Example: `sn_6125938`
`team_id`	string	No		Filter matches involving a specific team (optional). Example: `tm_0406`
`date_from`	string (date)	No		Filter matches from this date onwards (optional, format YYYY-MM-DD)
`date_to`	string (date)	No		Filter matches until this date (optional, format YYYY-MM-DD)
`utc_offset`	string	No	`+00:00`	UTC offset for date interpretation (e.g. `+05:30`, `-04:00`). Must match the pattern `±HH:MM` with `HH ≤ 14` and `MM ≤ 59`. Defaults to `+00:00` (UTC).
`matchday`	integer	No		Filter matches by matchday / round number (positive integer). Example: `1`
`status`	string — enum: `scheduled`, `live`, `finished`, `postponed`, `cancelled`	No		Filter by match status (optional). Values: `scheduled`, `live`, `finished`, `postponed`, `cancelled`
`stage`	string — enum: `regular`, `playoff`, `all`	No	`all`	Restrict to regular/group-stage fixtures, playoff/knockout fixtures, or all fixtures. Values: `regular`, `playoff`, `all`. Example: `regular`
`group`	string — enum: `A`, `B`, `C`, `D`, `E`, `F`, `G`, `H`, `I`, `J`, `K`, `L`	No		Filter by group letter. Requires `competition_id`; using `group` without `competition_id` returns 400.

Response (200)

{
  "data": [
    {
      "id": "mt_838955483",
      "competition_id": "comp_3039",
      "season_id": "sn_6125938",
      "matchday": 20,
      "stage_name": "round_of_16",
      "group_label": "A",
      "status": "finished",
      "utc_date": "2024-01-15T15:00:00.000Z",
      "home_team": {
        "id": "tm_0406",
        "name": "Liverpool"
      },
      "away_team": {
        "id": "tm_1002",
        "name": "Aston Villa"
      },
      "score": {
        "home": 2,
        "away": 1,
        "final_score": {
          "home": 5,
          "away": 4
        }
      },
      "odds_available": true,
      "live_odds_available": true,
      "xg_available": true
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

This page is generated from the live API contract at https://api.thestatsapi.com/llms.txt.