> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/schedule-and-calendar/leagues-and-seasons.md).

# Leagues and seasons

This guide covers how leagues and seasons are structured in the Motorsport API, how to retrieve them, and how to use them to navigate to the rest of the data hierarchy.

#### When to use this

Use leagues and seasons when you want to:

* Find the league ID and current season ID before making other requests
* Build a season selector for a race calendar or standings page
* Check whether a season is current, pending, or finished
* Retrieve all seasons for a given championship

#### The hierarchy

```
League (championship)
  └── Season (calendar year)
        └── Stage (race weekend)
              └── Fixture (individual session)
```

A **League** is the championship, for example the Formula 1 World Championship. A **Season** is a calendar year within that championship. Most other requests in the API require a `season_id` or `league_id`, so retrieving these first is the usual starting point.

#### Retrieving leagues

Get all leagues in your subscription:

```http
GET https://api.sportmonks.com/v3/motorsport/leagues
?api_token={your_token}
```

A league response looks like this:

```json
{
  "data": [
    {
      "id": 3468,
      "sport_id": 2,
      "country_id": 462,
      "name": "Formula 1",
      "active": 1,
      "short_code": "F1",
      "image_path": "https://cdn.sportmonks.com/images/motorsport/leagues/3468.png",
      "type": "formula_one",
      "sub_type": "formula_one",
      "last_played_at": "2025-12-07 13:00:00",
      "category": 1,
      "has_jerseys": false
    }
  ]
}
```

To get the current season alongside the league in one call:

```http
GET https://api.sportmonks.com/v3/motorsport/leagues
?api_token={your_token}&include=currentSeason
```

#### Retrieving seasons

Get all seasons for a specific league using the `seasonLeagues` filter:

```http
GET https://api.sportmonks.com/v3/motorsport/seasons
?api_token={your_token}&filters=seasonLeagues:3468
```

A season response looks like this:

```json
{
  "data": [
    {
      "id": 25273,
      "sport_id": 2,
      "league_id": 3468,
      "name": "2025",
      "finished": 0,
      "pending": 0,
      "is_current": 1,
      "starting_at": "2025-03-14",
      "ending_at": "2025-12-07",
      "standings_recalculated_at": "2025-11-23 19:15:31"
    }
  ]
}
```

`is_current` indicates the active season. `finished` and `pending` let you determine whether a season is complete or yet to begin.

To get the current season only, filter for `is_current` after fetching the list, or use the `currentSeason` include on the league:

```http
GET https://api.sportmonks.com/v3/motorsport/leagues/3468
?api_token={your_token}&include=currentSeason
```

#### Working with the data

**Find the current season ID**

{% tabs %}
{% tab title="First Tab" %}

```javascript
const API_TOKEN = 'your_token';

async function getCurrentSeasonId(leagueId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/seasons?api_token=${API_TOKEN}&filters=seasonLeagues:${leagueId}`
  );
  const { data } = await response.json();
  const current = data.find(s => s.is_current === 1);
  return current?.id ?? null;
}
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

API_TOKEN = "your_token"

def get_current_season(league_id):
    url = "https://api.sportmonks.com/v3/motorsport/seasons"
    params = {
        "api_token": API_TOKEN,
        "filters": f"seasonLeagues:{league_id}"
    }
    response = requests.get(url, params=params)
    seasons = response.json()["data"]
    current = next((s for s in seasons if s["is_current"] == 1), None)
    return current["id"] if current else None

season_id = get_current_season(3468)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
function getCurrentSeasonId(string $apiToken, int $leagueId): ?int {
    $url = "https://api.sportmonks.com/v3/motorsport/seasons?api_token={$apiToken}&filters=seasonLeagues:{$leagueId}";
    $response = json_decode(file_get_contents($url), true);
    foreach ($response['data'] as $season) {
        if ($season['is_current'] === 1) {
            return $season['id'];
        }
    }
    return null;
}
```

{% endtab %}
{% endtabs %}

**Build a season selector**

{% tabs %}
{% tab title="JavaScript" %}

```javascript
async function getAllSeasons(leagueId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/seasons?api_token=${API_TOKEN}&filters=seasonLeagues:${leagueId}&order=desc`
  );
  const { data } = await response.json();
  return data.map(s => ({ id: s.id, name: s.name, isCurrent: s.is_current === 1 }));
}
```

{% endtab %}

{% tab title="Python" %}

```python
def get_all_seasons(league_id):
    url = "https://api.sportmonks.com/v3/motorsport/seasons"
    params = {
        "api_token": API_TOKEN,
        "filters": f"seasonLeagues:{league_id}",
        "order": "desc"
    }
    response = requests.get(url, params=params)
    return [
        {"id": s["id"], "name": s["name"], "is_current": s["is_current"]}
        for s in response.json()["data"]
    ]
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
const API_TOKEN = 'YOUR_TOKEN';
function get_all_seasons($leagueId) {
    $url = "https://api.sportmonks.com/v3/motorsport/seasons";
    $params = [
        "api_token" => API_TOKEN,
        "filters" => "seasonLeagues:" . $leagueId,
        "order" => "desc"
    ];
    $requestUrl = $url . "?" . http_build_query($params);
    $response = file_get_contents($requestUrl);
    if ($response === false) {
        return [];
    }
    $json = json_decode($response, true);
    $data = $json["data"] ?? [];
    return array_map(function ($season) {
        return [
            "id" => $season["id"] ?? null,
            "name" => $season["name"] ?? null,
            "isCurrent" => isset($season["is_current"]) && $season["is_current"] === 1
        ];
    }, $data);
}
```

{% endtab %}
{% endtabs %}

#### Common pitfalls

**Using `league_id` where `season_id` is required.** Most data endpoints (fixtures, standings, stages) filter by `season_id`, not `league_id`. Always resolve the current `season_id` first rather than passing the league ID to a downstream request.

**Assuming `is_current` returns a boolean.** The `is_current` field returns an integer: `1` for the current season, `0` otherwise. Use `=== 1` rather than a truthy check in strictly typed code.

**Not paginating the seasons list.** A championship with many years of history can have more seasons than the default page size. Use cursor-based pagination to retrieve the full list. See [Pagination](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/introduction/pagination).

**`tie_breaker_rule_id` and `games_in_current_week` are not used in the Motorsport API.** These fields exist on the Season entity for cross-sport compatibility but are not applicable to motorsport data. Treat them as null.

#### Common errors

| Status | Likely cause                                                |
| ------ | ----------------------------------------------------------- |
| `401`  | Missing or invalid `api_token`                              |
| `404`  | The league or season ID does not exist in your subscription |

#### See also

**Related tutorials**

* [Schedule](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/schedule-and-calendar/schedule)
* [Stages](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/schedule-and-calendar/stages)
* [Pagination](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/introduction/pagination)
* [Filter and select fields - Filtering](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/filter-and-select-fields/filtering)

**Reference**

* [League entity](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/league.md)
* [Season entity](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/season.md)

#### FAQ

**What is the Formula 1 league ID?** The league ID for Formula 1 is `3468`, as shown in the example response above. You can confirm this by calling `GET /motorsport/leagues` with your token.

**How do I get the season ID for a specific year?** Filter seasons by league, then match on the `name` field which contains the calendar year (e.g. `"2025"`).

**Is there always exactly one current season?** In practice yes, but defensively code for the possibility of zero results from the `is_current` filter in case the season transition has not yet been applied on Sportmonks' side.

**What does `standings_recalculated_at` mean?** It is the timestamp of the last standings recalculation for that season. Useful for knowing whether standings data is fresh after a race weekend.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/schedule-and-calendar/leagues-and-seasons.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.