> ## Documentation Index
> Fetch the complete documentation index at: https://www.thestatsapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /football/matches — list and filter matches

> Retrieve a paginated list of football matches. Filter by competition, season, team, date range, or status to find fixtures, results, and live games.

List matches

## Endpoint

```text theme={null}
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)

```json theme={null}
{
  "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
  }
}
```

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