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

# Find competition, team, player and match IDs

> Look up the comp_, sn_, tm_, pl_ and mt_ IDs every other request needs, using search, season lists and the is_mens_team filter.

Use this page to find the IDs that every other endpoint needs.

<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), write a server-side function that looks up the team_id for Arsenal's men's team and the current Premier League season_id, then prints both.
  ```
</Tip>

## How IDs work

IDs are strings with a prefix that tells you what they point to. You look them up by name with the requests below, then pass them to other endpoints.

| Prefix | What it is | Example |
| - | - | - |
| `comp_` | Competition | `comp_3039` (Premier League) |
| `sn_` | Season of a competition | `sn_8406098` (Premier League 26/27) |
| `tm_` | Team | `tm_9145` (Arsenal) |
| `pl_` | Player | `pl_45126714` (Bukayo Saka) |
| `mt_` | Match | `mt_200199332` (Arsenal v Leeds United) |

<Note>
  Just need one ID? Use the [ID finder](https://www.thestatsapi.com/id-finder) in your dashboard (you need to be logged in).
</Note>

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

## Find a competition

Search by name. The best match comes first. Add `sort=name` if you want A to Z instead.

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.thestatsapi.com/api/football/competitions?search=Premier&per_page=3" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://api.thestatsapi.com/api/football/competitions?search=Premier&per_page=3",
    { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
  );
  const { data } = await res.json();
  console.log(data[0].id); // "comp_3039"
  ```
</CodeGroup>

Response (trimmed):

```json Response theme={null}
{
  "data": [
    {
      "id": "comp_3039",
      "name": "Premier League",
      "country": "England",
      "country_code": "GB",
      "subdivision_code": "GB-ENG",
      "type": "league",
      "odds_available": true,
      "xg_available": true
    },
    {
      "id": "comp_84287",
      "name": "Egyptian Premier League",
      "country": "Egypt",
      "country_code": "EG",
      "type": "league"
    }
  ],
  "meta": { "page": 1, "per_page": 3, "total": 11, "total_pages": 4 }
}
```

You can also filter instead of searching:

* `country_code=GB-ENG&type=league` lists English leagues. `GB` returns every UK nation; `GB-ENG`, `GB-SCT`, `GB-WLS` and `GB-NIR` return one. Other countries use codes such as `DE` or `ES`.
* `country=Spain` matches the country name.

## Find the current season and past seasons

Fetch the competition to get `current_season_id`.

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

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://api.thestatsapi.com/api/football/competitions/comp_3039",
    { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
  );
  const { data } = await res.json();
  console.log(data.current_season_id); // "sn_8406098"
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "id": "comp_3039",
    "name": "Premier League",
    "type": "league",
    "has_team_stats": true,
    "has_player_stats": true,
    "odds_available": true,
    "xg_available": true,
    "current_season_id": "sn_8406098",
    "total_teams": 20
  }
}
```

For older seasons, list them. They come back newest first, and the current one has `is_current: true`.

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

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://api.thestatsapi.com/api/football/competitions/comp_3039/seasons",
    { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
  );
  const { data } = await res.json();
  const lastSeason = data.find((s) => s.year === "25/26");
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    { "id": "sn_8406098", "name": "Premier League 26/27", "year": "26/27", "start_year": 2026, "end_year": 2027, "is_current": true },
    { "id": "sn_6125938", "name": "Premier League 25/26", "year": "25/26", "start_year": 2025, "end_year": 2026, "is_current": false }
  ]
}
```

A season ID belongs to one competition. If you send a `season_id` with a different `competition_id`, you get a `400` error: "season\_id does not belong to competition\_id".

## Find a team (men's or women's)

Search by name. A club's men's and women's teams often share a name, so check `is_mens_team`.

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.thestatsapi.com/api/football/teams?search=Arsenal&per_page=5" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://api.thestatsapi.com/api/football/teams?search=Arsenal&per_page=5",
    { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
  );
  const { data } = await res.json();
  ```
</CodeGroup>

Response (trimmed):

```json Response theme={null}
{
  "data": [
    {
      "id": "tm_9145",
      "name": "Arsenal",
      "country": "England",
      "is_mens_team": true,
      "primary_competition": { "id": "comp_3039", "name": "Premier League" }
    },
    {
      "id": "tm_515555",
      "name": "Arsenal",
      "country": "England",
      "is_mens_team": false,
      "primary_competition": { "id": "comp_08207", "name": "Women's Super League" }
    },
    {
      "id": "tm_033813",
      "name": "Arsenal U21",
      "country": "England",
      "is_mens_team": true,
      "primary_competition": { "id": "comp_0488", "name": "Football League Trophy" }
    }
  ],
  "meta": { "page": 1, "per_page": 5, "total": 15, "total_pages": 3 }
}
```

To get one side only, add `is_mens_team=true` (men) or `is_mens_team=false` (women). On a team, `is_mens_team` is `null` when it isn't known.

```bash theme={null}
curl "https://api.thestatsapi.com/api/football/teams?search=Arsenal&is_mens_team=true&per_page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

To list every team in a season, filter by competition and season instead: `/football/teams?competition_id=comp_3039&season_id=sn_8406098` returns the 20 Premier League teams.

## Find a player

Search needs at least 3 characters. It ignores case and accents, so `odegaard` finds "Ødegaard".

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.thestatsapi.com/api/football/players?search=saka&per_page=2" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://api.thestatsapi.com/api/football/players?search=saka&per_page=2",
    { headers: { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` } }
  );
  const { data } = await res.json();
  console.log(data[0].id); // "pl_45126714"
  ```
</CodeGroup>

Response (trimmed):

```json Response theme={null}
{
  "data": [
    {
      "id": "pl_45126714",
      "name": "Bukayo Saka",
      "position": "F",
      "date_of_birth": "2001-09-05",
      "nationality": "England",
      "current_team": { "id": "tm_9145", "name": "Arsenal", "jersey_number": 7 }
    }
  ],
  "meta": { "page": 1, "per_page": 2, "total": 157, "total_pages": 79 }
}
```

Other ways to find players:

* `/football/players?team_id=tm_9145` lists a team's current players. Add `position=F` (or `G`, `D`, `M`) to narrow it.
* `/football/teams/tm_9145/players` returns the squad with extra profile fields.
* `/football/players?player_ids=pl_45126714,pl_29627593` fetches several players in one call.

## Find a match

Match IDs come from `/football/matches`. Filter by team, competition, season, date or status. For example, a team's next fixture:

```bash theme={null}
curl "https://api.thestatsapi.com/api/football/matches?team_id=tm_9145&status=scheduled&sort=utc_date&per_page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

See [Fixtures and results](/docs/guides/fixtures-and-results) for every filter.

## API reference

* [List competitions](/docs/api-reference/competitions/list) and [Get a competition](/docs/api-reference/competitions/get)
* [List a competition's seasons](/docs/api-reference/competitions/seasons)
* [List teams](/docs/api-reference/teams/list) and [Get a team's squad](/docs/api-reference/teams/players)
* [List players](/docs/api-reference/players/list)
* [List matches](/docs/api-reference/matches/list)


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