> ## 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.

> ## Agent Instructions
> For the complete API reference (every endpoint, query parameter and response field), fetch https://api.thestatsapi.com/llms.txt. Only use endpoints, parameters and fields listed there.
> Base URL: https://api.thestatsapi.com/api. Auth header: Authorization: Bearer YOUR_API_KEY. Keep the key in server-side code only.

# Data coverage

> Check which competitions, seasons and data types exist before you build, using the coverage endpoints and competition availability flags.

Use this page to check what data exists for a competition and season before you build on it.

<Tip>
  **Fastest way: ask your AI.** Set up your coding tool once with [Build with AI](/docs/build-with-ai), then paste:

  ```text theme={null}
  Using TheStatsAPI (reference: https://api.thestatsapi.com/llms.txt), call GET /coverage/leagues/comp_8814 from the server and print a table of LaLiga seasons with coverage_pct for xg, player_stats and closing_odds. Skip seasons with status not_loaded.
  ```
</Tip>

Just want a quick look? Browse the [coverage page](https://www.thestatsapi.com/coverage).

## History depth varies

How far back data goes depends on the competition, and on the data type within it. Don't assume a fixed number of years. Check the competitions you need.

Some examples from the coverage endpoints:

| Competition | Seasons from |
| - | - |
| Premier League | 2014/15 |
| LaLiga, Bundesliga, Serie A, Ligue 1, UEFA Champions League | 2020/21 |
| MLS | 2020 |

Within one competition, data types start at different seasons. In the Premier League:

| Data type | Available from |
| - | - |
| Fixtures, lineups, team stats, player stats, standings | 2014/15 |
| Closing odds | 2015/16 |
| xG | 2022/23 |
| Opening odds | 2026/27 |

### Odds history

Odds history is thinner than match data:

* **Before the 2026/27 season (around August 2026)**, matches mostly have closing prices only (the last price before kickoff), mostly from Bet365.
* **From the 2026/27 season**, matches can also have opening prices, and prices from more bookmakers: Bet365, Paddy Power, BetMGM UK, Pinnacle and Betfair Exchange.

Check `opening_odds` and `closing_odds` in the coverage response for the exact seasons you need.

## The coverage endpoints

| Endpoint | Use it to |
| - | - |
| [`GET /coverage/summary`](/docs/api-reference/coverage/summary) | See headline totals: competitions, seasons and finished matches. |
| [`GET /coverage/leagues`](/docs/api-reference/coverage/leagues) | Find competitions that have a data type. Filter with `data_type` and `search`. |
| [`GET /coverage/leagues/{competition_id}`](/docs/api-reference/coverage/league) | See every season of one competition, with match counts and the percentage of matches that have each data type. |

## Check coverage before you build

<Steps>
  <Step title="Find competitions with the data you need">
    Add `data_type` to list only competitions that have it, and `search` to filter by name.

    <CodeGroup>
      ```bash curl theme={null}
      curl "https://api.thestatsapi.com/api/coverage/leagues?data_type=xg&search=Premier" \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch(
        "https://api.thestatsapi.com/api/coverage/leagues?data_type=xg&search=Premier",
        { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
      );
      const { data } = await res.json();
      for (const league of data) {
        console.log(league.id, league.name, league.seasons.first?.year, "to", league.seasons.last?.year);
      }
      ```
    </CodeGroup>

    Each row shows the competition, how many seasons are loaded, which data types it has and the state of its latest season (trimmed):

    ```json theme={null}
    {
      "id": "comp_3039",
      "name": "Premier League",
      "country": "England",
      "seasons": {
        "count": 13,
        "first": { "id": "sn_612289", "year": "14/15" },
        "last": { "id": "sn_8406098", "year": "26/27" }
      },
      "data_types": {
        "fixtures": { "available": true },
        "xg": { "available": true },
        "opening_odds": { "available": true },
        "closing_odds": { "available": true },
        "player_stats": { "available": true }
      },
      "latest_season": {
        "id": "sn_8406098",
        "year": "26/27",
        "status": "in_progress",
        "finished_events": 50,
        "total_events": 100
      },
      "total_finished_events": 4610
    }
    ```
  </Step>

  <Step title="Check each season">
    Ask for one competition to see coverage season by season.

    <CodeGroup>
      ```bash curl theme={null}
      curl "https://api.thestatsapi.com/api/coverage/leagues/comp_3039" \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```

      ```javascript JavaScript theme={null}
      const res = await fetch("https://api.thestatsapi.com/api/coverage/leagues/comp_3039", {
        headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` },
      });
      const { data } = await res.json();
      for (const season of data.seasons) {
        if (season.status === "not_loaded") continue;
        console.log(season.year, "xG:", season.data_types.xg.coverage_pct ?? 0, "%");
      }
      ```
    </CodeGroup>

    Each season shows its status, match counts, and for each data type how many finished matches have it (trimmed):

    ```json theme={null}
    {
      "id": "sn_6125938",
      "name": "Premier League 25/26",
      "year": "25/26",
      "status": "complete",
      "events": { "finished": 380, "total": 380 },
      "data_types": {
        "xg": { "available": true, "covered_events": 380, "coverage_pct": 100 },
        "opening_odds": { "available": false, "covered_events": 0, "coverage_pct": 0 },
        "closing_odds": { "available": true, "covered_events": 380, "coverage_pct": 100 },
        "player_stats": { "available": true, "covered_events": 380, "coverage_pct": 100 },
        "standings": { "available": true }
      }
    }
    ```
  </Step>

  <Step title="Use the season ID">
    Coverage uses the same `sn_` season IDs as every other endpoint. Pass the one you picked to `/football/matches`, standings or stats.
  </Step>
</Steps>

## Data types

| Key | What it means | Where you get it |
| - | - | - |
| `fixtures` | Matches are loaded. | `/football/matches` |
| `team_stats` | Team statistics for each match. | `/football/matches/{match_id}/stats` |
| `xg` | Expected goals for the match. | `expected_goals` in `/football/matches/{match_id}/stats` |
| `player_stats` | Player statistics for each match. | `/football/matches/{match_id}/player-stats` |
| `lineups` | Starting lineups and formations. | `/football/matches/{match_id}/lineups` |
| `standings` | A league table exists for the season. | `/football/competitions/{competition_id}/seasons/{season_id}/standings` |
| `closing_odds` | The last pre-match prices. | `last_seen` in `/football/matches/{match_id}/odds` |
| `opening_odds` | The first prices captured. | `opening` in `/football/matches/{match_id}/odds` |
| `odds` | Same as `closing_odds`. Kept for older code. | |

Each data type has `available` (`true` or `false`). On `/coverage/leagues/{competition_id}`, most also have:

* `covered_events`: finished matches in the season that have this data.
* `coverage_pct`: those matches as a percentage of all finished matches, to one decimal place.

New data type keys may be added, so ignore keys your code doesn't recognise.

## Season status

| `status` | Meaning |
| - | - |
| `complete` | All loaded matches are finished. |
| `in_progress` | Matches are still to be played. |
| `not_loaded` | The season is known but has no matches loaded. |

## Good to know

* **Only finished matches are counted** in `covered_events`, `coverage_pct` and `finished_events`.
* **For a season in progress, `total` can be lower than the full season**, because fixtures are still being added.
* **Coverage responses are cached for several hours**, so the latest matches can take a while to show up in the counts.
* **`seasons.first` and `seasons.last` on `/coverage/leagues` are a quick guide.** For the exact list of seasons, use `/coverage/leagues/{competition_id}`. Seasons there aren't always in date order.

## Quick check with competition flags

Every competition also carries flags: `has_team_stats`, `has_player_stats`, `xg_available`, `odds_available` and `live_odds_available`. They tell you whether the data type exists anywhere in the competition, not which seasons have it. See [Data model](/docs/concepts/data-model#availability-flags).

```bash theme={null}
curl "https://api.thestatsapi.com/api/football/competitions/comp_3039" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Next steps

* [Find IDs](/docs/guides/finding-ids): get the `competition_id` and `season_id` for the leagues you picked.
* [Odds](/docs/guides/odds): which bookmakers and markets a match has.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.