> 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/stages.md).

# Stages

This guide covers how stages work in the Motorsport API, how to retrieve them, and how to use them to access the sessions within a race weekend.

#### When to use this

Use the Stages endpoints when you want to:

* Retrieve a specific race weekend by its ID
* List all race weekends in a season with their dates and status
* Get all sessions (fixtures) for a specific race weekend
* Check whether a race weekend is finished or currently active

#### What a stage is

A stage represents a race weekend. It groups all the individual sessions at a single circuit: practice sessions, qualifying, the sprint race (if applicable), and the main race. Each session within the weekend is a Fixture.

```
Stage (race weekend: "Bahrain Grand Prix 2025")
  └── Fixtures
        ├── Practice 1
        ├── Practice 2
        ├── Practice 3
        ├── Qualifying
        └── Race
```

#### The Stage entity fields

<table data-search="false"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique ID of the stage</td></tr><tr><td><code>sport_id</code></td><td>Sport ID (2 for Motorsport)</td></tr><tr><td><code>league_id</code></td><td>The championship this weekend belongs to</td></tr><tr><td><code>season_id</code></td><td>The season this weekend belongs to</td></tr><tr><td><code>type_id</code></td><td>The stage type (e.g. race weekend, test session)</td></tr><tr><td><code>name</code></td><td>The name of the race weekend (e.g. "Bahrain Grand Prix 2025")</td></tr><tr><td><code>sort_order</code></td><td>The round number within the season</td></tr><tr><td><code>finished</code></td><td>Whether the weekend is complete</td></tr><tr><td><code>is_current</code></td><td>Whether this is the current active race weekend</td></tr><tr><td><code>starting_at</code></td><td>Start date of the weekend</td></tr><tr><td><code>ending_at</code></td><td>End date of the weekend</td></tr></tbody></table>

`games_in_current_week` and `tie_breaker_rule_id` are not used in the Motorsport API.

#### Retrieving stages

Get all stages for a season:

```http
GET https://api.sportmonks.com/v3/motorsport/stages
?api_token={your_token}&filters=stageSeasons:25273
```

Get a specific stage by ID:

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

Get all sessions within a stage:

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

Get stages with their type resolved:

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

#### Available includes

`sport` `league` `season` `type` `fixtures`

#### Working with the data

**List all race weekends in a season**

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

```javascript
const API_TOKEN = 'your_token';

async function getSeasonStages(seasonId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/stages?api_token=${API_TOKEN}&filters=stageSeasons:${seasonId}&order=asc`
  );
  const { data } = await response.json();
  return data;
}
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

API_TOKEN = "your_token"

def get_season_stages(season_id):
    url = "https://api.sportmonks.com/v3/motorsport/stages"
    params = {
        "api_token": API_TOKEN,
        "filters": f"stageSeasons:{season_id}",
        "order": "asc"
    }
    response = requests.get(url, params=params)
    return response.json()["data"]

stages = get_season_stages(25273)
for stage in stages:
    status = "Finished" if stage["finished"] else "Upcoming"
    print(f"Round {stage['sort_order']}: {stage['name']} ({status})")
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
function getSeasonStages(string $apiToken, int $seasonId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/stages
           ?api_token={$apiToken}&filters=stageSeasons:{$seasonId}&order=asc";
    $response = json_decode(file_get_contents($url), true);
    return $response['data'];
}
```

{% endtab %}
{% endtabs %}

**Get all sessions for a race weekend**

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

```javascript
async function getStageSessions(stageId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/stages/${stageId}?api_token=${API_TOKEN}&include=fixtures`
  );
  const { data } = await response.json();
  return data.fixtures.sort((a, b) =>
    new Date(a.starting_at) - new Date(b.starting_at)
  );
}
```

{% endtab %}

{% tab title="Python" %}

```python
def get_stage_sessions(stage_id):
    url = f"https://api.sportmonks.com/v3/motorsport/stages/{stage_id}"
    params = {
        "api_token": API_TOKEN,
        "include": "fixtures"
    }
    response = requests.get(url, params=params)
    stage = response.json()["data"]
    return sorted(stage["fixtures"], key=lambda f: f["starting_at"])
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
function getStageSessions(string $apiToken, int $stageId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/stages/{$stageId}
            ?api_token={$apiToken}&include=fixtures";
    $response = json_decode(file_get_contents($url), true);
    $fixtures = $response['data']['fixtures'];
    usort($fixtures, fn($a, $b) => strcmp($a['starting_at'], $b['starting_at']));
    return $fixtures;
}
```

{% endtab %}
{% endtabs %}

**Find the current active race weekend**

```python
def get_current_stage(season_id):
    stages = get_season_stages(season_id)
    return next((s for s in stages if s["is_current"]), None)
```

```javascript
async function getCurrentStage(seasonId) {
  const stages = await getSeasonStages(seasonId);
  return stages.find(s => s.is_current) ?? null;
}
```

#### Common pitfalls

**Using the Schedule endpoint when you need includes.** The Schedule endpoint returns a denormalised view of stages and fixtures together, but has no include options. If you need to attach results, lineups, or venue details to fixtures within a weekend, query the stage with `&include=fixtures` first, then enrich individual fixtures via the Fixtures endpoint.

**Confusing `sort_order` with `id`.** `sort_order` is the round number within the season (1, 2, 3...). `id` is the unique database ID of the stage. Use `sort_order` for display and sorting, `id` for API lookups.

**`finished` returns a boolean, `is_current` also returns a boolean.** Both are true booleans on the Stage entity (unlike `is_current` on Season which returns an integer). Check the entity page for the specific type of each field before writing comparison logic.

**`type_id` requires a separate lookup.** The stage type (e.g. race weekend vs test session) is an integer ID that maps to a type entity. Include `type` to get the human-readable label, or fetch all types once and cache them locally.

#### Common errors

| Status | Likely cause                                                 |
| ------ | ------------------------------------------------------------ |
| `401`  | Missing or invalid `api_token`                               |
| `404`  | The `stage_id` does not exist or is not in your subscription |

#### See also

**Related tutorials**

* [Leagues and seasons](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/schedule-and-calendar/leagues-and-seasons)
* [Schedule](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/schedule-and-calendar/schedule)
* [Fixtures](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/fixtures)
* [Filter and select fields - Filtering](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/filter-and-select-fields/filtering)

**Reference**

* [Stage entity](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/stage.md)
* [Schedule entity](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/schedule.md)

#### FAQ

**What is the difference between a stage and a fixture?** A stage is the race weekend as a whole. A fixture is a single session within that weekend (e.g. Practice 1 or the Race). A stage contains multiple fixtures.

**How do I find a stage ID if I only know the race name or round number?** Query all stages for the season with `stageSeasons` filter, then match on `name` or `sort_order`.

**Does each season always start at `sort_order` 1?** Yes. `sort_order` reflects the round number within the season, starting at 1.

**How do I tell if a weekend has a sprint race?** Fetch the stage with `&include=fixtures` and check the fixture names. A sprint weekend will include a `"Sprint Qualifying"` and `"Sprint"` fixture in addition to the standard sessions.


---

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