> ## 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/competitions — list competitions

> Returns a paginated list of football competitions. Filter by country, type, or name to find competition IDs for use in subsequent queries.

List all competitions

## Endpoint

```text theme={null}
GET https://api.thestatsapi.com/api/football/competitions
```

Retrieve a paginated list of football competitions

## 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. |
| `country`      | string                                       | No       |         | Filter by country name (optional)                                                                          |
| `country_code` | string                                       | No       |         | Filter by country code (optional)                                                                          |
| `type`         | string — enum: `league`, `cup`, `tournament` | No       |         | Filter by competition type (optional). Values: `league`, `cup`, `tournament`                               |
| `search`       | string                                       | No       |         | Search competitions by name (case-insensitive partial match). Example: `Premier`                           |

## Response (200)

```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": 100,
    "total_pages": 5
  }
}
```

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