> ## 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 started with The Stats API

> Make your first authenticated API call, verify the service is healthy, and start fetching football data in under five minutes.

This guide walks through the first requests most integrations need: verify connectivity, list competitions, list matches, and fetch details for one match.

<Steps>
  <Step title="Get your API key">
    Create an API key in your account dashboard and store it in an environment variable.

    ```bash theme={null}
    export STATS_API_KEY="YOUR_API_KEY"
    ```
  </Step>

  <Step title="Check API health">
    The health endpoint is public and does not require authentication.

    ```bash theme={null}
    curl --request GET \
      --url https://api.thestatsapi.com/api/health
    ```

    A healthy API returns JSON like this:

    ```json theme={null}
    {
      "status": "healthy",
      "timestamp": "2026-04-20T10:00:00Z"
    }
    ```
  </Step>

  <Step title="Fetch competitions">
    List competitions to find stable competition IDs such as `comp_3039`.

    <CodeGroup>
      ```bash curl theme={null}
      curl --request GET \
        --url "https://api.thestatsapi.com/api/football/competitions?per_page=20" \
        --header "Authorization: Bearer $STATS_API_KEY"
      ```

      ```python Python theme={null}
      import os
      import requests

      response = requests.get(
          "https://api.thestatsapi.com/api/football/competitions",
          headers={"Authorization": f"Bearer {os.environ['STATS_API_KEY']}"},
          params={"per_page": 20},
      )

      print(response.json())
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        "https://api.thestatsapi.com/api/football/competitions?per_page=20",
        {
          headers: {
            Authorization: `Bearer ${process.env.STATS_API_KEY}`,
          },
        }
      );

      console.log(await response.json());
      ```
    </CodeGroup>

    Example response:

    ```json theme={null}
    {
      "data": [
        {
          "id": "comp_3039",
          "name": "Premier League",
          "country": "England",
          "country_code": "GB",
          "subdivision_code": "GB-ENG",
          "confederation": null,
          "type": "league",
          "has_team_stats": true,
          "has_player_stats": true,
          "odds_available": true,
          "live_odds_available": true,
          "xg_available": true
        }
      ],
      "meta": {
        "page": 1,
        "per_page": 20,
        "total": 48,
        "total_pages": 3
      }
    }
    ```
  </Step>

  <Step title="Fetch matches">
    Query matches with date filters, competition/season filters, status, stage, or group.

    ```bash theme={null}
    curl --request GET \
      --url "https://api.thestatsapi.com/api/football/matches?competition_id=comp_3039&season_id=sn_6125938&date_from=2026-04-19&date_to=2026-04-20" \
      --header "Authorization: Bearer $STATS_API_KEY"
    ```

    Match list responses include IDs such as `mt_838955483` and flags such as `xg_available`, `odds_available`, and `live_odds_available`.
  </Step>

  <Step title="Fetch a match detail">
    Use the match ID from a list response to retrieve the full match record.

    <CodeGroup>
      ```bash curl theme={null}
      curl --request GET \
        --url https://api.thestatsapi.com/api/football/matches/mt_838955483 \
        --header "Authorization: Bearer $STATS_API_KEY"
      ```

      ```python Python theme={null}
      import os
      import requests

      match_id = "mt_838955483"
      response = requests.get(
          f"https://api.thestatsapi.com/api/football/matches/{match_id}",
          headers={"Authorization": f"Bearer {os.environ['STATS_API_KEY']}"},
      )

      print(response.json())
      ```

      ```javascript JavaScript theme={null}
      const matchId = "mt_838955483";
      const response = await fetch(
        `https://api.thestatsapi.com/api/football/matches/${matchId}`,
        {
          headers: {
            Authorization: `Bearer ${process.env.STATS_API_KEY}`,
          },
        }
      );

      console.log(await response.json());
      ```
    </CodeGroup>
  </Step>
</Steps>

<Note>
  After you have IDs, use the reference to fetch seasons, standings, squads, team/player stats, live stats, lineups, timelines, shotmaps, heatmaps, and odds.
</Note>