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

# Get league tables and group standings

> Get the current league table, a past season's table, tournament group tables and a team's standings history.

Use this page to show league tables, including past seasons and tournament groups.

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

  ```text Prompt wrap theme={null}
  Using TheStatsAPI (reference: https://api.thestatsapi.com/llms.txt), build a server route that returns the current Premier League table (position, team, played, goal difference, points) using the competition's current_season_id. Keep the API key server-side.
  ```
</Tip>

## How it fits together

Standings belong to a season of a competition, so you need two IDs: `competition_id` and `season_id`.

<Steps>
  <Step title="Find the competition">
    `GET /football/competitions?search=Premier` returns `comp_3039`. See [Find IDs](/docs/guides/finding-ids).
  </Step>

  <Step title="Pick the season">
    Use `current_season_id` from `GET /football/competitions/comp_3039`, or pick an older one from `GET /football/competitions/comp_3039/seasons`.
  </Step>

  <Step title="Get the table">
    `GET /football/competitions/comp_3039/seasons/{season_id}/standings`
  </Step>
</Steps>

The JavaScript examples run on your server and read your key from the `THESTATSAPI_API_KEY` environment variable.

## Current league table

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

  ```javascript JavaScript theme={null}
  const headers = { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` };
  const base = "https://api.thestatsapi.com/api/football/competitions/comp_3039";

  const { data: comp } = await (await fetch(base, { headers })).json();
  const { data: table } = await (
    await fetch(`${base}/seasons/${comp.current_season_id}/standings`, { headers })
  ).json();

  for (const row of table) {
    console.log(row.position, row.team.name, row.matches_played, row.goal_difference, row.points);
  }
  ```
</CodeGroup>

Response (first two rows of 20):

```json Response theme={null}
{
  "data": [
    {
      "team": { "id": "tm_3039", "name": "Manchester City" },
      "position": 1,
      "matches_played": 5,
      "wins": 5,
      "draws": 0,
      "losses": 0,
      "goals_for": 13,
      "goals_against": 5,
      "goal_difference": 8,
      "points": 15,
      "group_label": null
    },
    {
      "team": { "id": "tm_9145", "name": "Arsenal" },
      "position": 2,
      "matches_played": 5,
      "wins": 4,
      "draws": 0,
      "losses": 1,
      "goals_for": 8,
      "goals_against": 4,
      "goal_difference": 4,
      "points": 12,
      "group_label": null
    }
  ]
}
```

Rows are sorted by `position`. The table isn't paginated, so one call returns every team.

## A past season

Swap in an older `season_id` from the seasons list. Premier League 25/26 is `sn_6125938`:

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

The first row is Arsenal: 38 played, 26 wins, 85 points.

How far back tables go depends on the competition. Check [Coverage](/docs/concepts/coverage) before you promise a season to your users. If the `season_id` belongs to a different competition, you get a `400` error: "season\_id does not belong to competition\_id".

## Tournament groups

For tournaments with a group stage (World Cup, EURO, AFCON and so on), list the groups first, then fetch one group's table.

<CodeGroup>
  ```bash curl theme={null}
  # 1. Groups in the 2022 World Cup
  curl "https://api.thestatsapi.com/api/football/competitions/comp_6107/seasons/sn_326766/groups" \
    -H "Authorization: Bearer YOUR_API_KEY"

  # 2. Group A table
  curl "https://api.thestatsapi.com/api/football/competitions/comp_6107/seasons/sn_326766/standings?group=A" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const headers = { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` };
  const season = "https://api.thestatsapi.com/api/football/competitions/comp_6107/seasons/sn_326766";

  const { data: groups } = await (await fetch(`${season}/groups`, { headers })).json();
  // [{ group_label: "A", name: "Group A" }, ... { group_label: "H", name: "Group H" }]

  const { data: groupA } = await (await fetch(`${season}/standings?group=A`, { headers })).json();
  ```
</CodeGroup>

Group A response (first row of 4):

```json Response theme={null}
{
  "data": [
    {
      "team": { "id": "tm_41792", "name": "Netherlands" },
      "position": 1,
      "matches_played": 3,
      "wins": 2,
      "draws": 1,
      "losses": 0,
      "goals_for": 5,
      "goals_against": 1,
      "goal_difference": 4,
      "points": 7,
      "group_label": "A"
    }
  ]
}
```

Without `group`, you get every group's table, sorted by `group_label` and then `position`.

<Note>
  Some competitions have no table. Knockout-only cups (such as the FA Cup) return an empty list, and `/groups` returns an empty list for leagues without groups.
</Note>

## A team's standings history

To build a "season by season" view for one team, list the competitions and seasons where it has a table entry. Then fetch each table you need.

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.thestatsapi.com/api/football/teams/tm_9145/standings" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.thestatsapi.com/api/football/teams/tm_9145/standings", {
    headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` },
  });
  const { data } = await res.json();
  for (const { competition, seasons } of data) {
    console.log(competition.name, seasons.map((s) => s.id));
  }
  ```
</CodeGroup>

Response (trimmed):

```json Response theme={null}
{
  "data": [
    {
      "competition": { "id": "comp_3039", "name": "Premier League" },
      "seasons": [
        { "id": "sn_8406098", "name": "Premier League 26/27", "group_label": null },
        { "id": "sn_6125938", "name": "Premier League 25/26", "group_label": null }
      ]
    },
    {
      "competition": { "id": "comp_7739", "name": "UEFA Europa League" },
      "seasons": [
        { "id": "sn_706199", "name": "UEFA Europa League 22/23", "group_label": "A" }
      ]
    }
  ]
}
```

This endpoint lists where the team has standings, not its positions. For the position, fetch the full table, using `group_label` as the `group` filter when it isn't `null`. For one season's record, [Get a team's season stats](/docs/api-reference/teams/stats) returns position, points and form in one call.

## API reference

* [Get season standings](/docs/api-reference/competitions/standings)
* [List groups in a season](/docs/api-reference/competitions/groups)
* [List a competition's seasons](/docs/api-reference/competitions/seasons)
* [List a team's standings history](/docs/api-reference/teams/standings)


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