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

# Fixtures

This guide covers how to retrieve fixtures, understand the different session types within a race weekend, and enrich fixture responses with results, lineups, and session metadata.

#### When to use this

Use the Fixtures endpoints when you want to:

* Retrieve a specific session by its ID
* Get all sessions across a season or date range
* Enrich a session with its results, lineup, lap data, or track metadata
* Check the current state of a session or how many laps have been completed
* Detect recently updated fixtures for syncing a local database

#### What a fixture is

A fixture is a single session within a race weekend: a practice session, qualifying session, sprint qualifying, sprint race, or the main race. Multiple fixtures belong to a stage (race weekend), which belongs to a season, which belongs to a league.

#### The Fixture entity fields

<table data-search="false"><thead><tr><th>Field</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>id</code></td><td>Unique ID of the fixture</td><td>integer</td></tr><tr><td><code>sport_id</code></td><td>Sport ID (2 for Motorsport)</td><td>integer</td></tr><tr><td><code>league_id</code></td><td>The championship this session belongs to</td><td>integer</td></tr><tr><td><code>season_id</code></td><td>The season this session belongs to</td><td>integer</td></tr><tr><td><code>stage_id</code></td><td>The race weekend this session belongs to</td><td>integer</td></tr><tr><td><code>state_id</code></td><td>The current state of the session</td><td>integer</td></tr><tr><td><code>venue_id</code></td><td>The circuit where this session is held</td><td>integer</td></tr><tr><td><code>name</code></td><td>The session name (e.g. "Practice 1", "Race")</td><td>string</td></tr><tr><td><code>starting_at</code></td><td>Start date and time in UTC</td><td>date</td></tr><tr><td><code>starting_at_timestamp</code></td><td>Start time as a Unix timestamp</td><td>integer</td></tr><tr><td><code>result_info</code></td><td>Final result summary (populated after session ends)</td><td>string</td></tr><tr><td><code>leg</code></td><td>Session position within its type (e.g. <code>"2/3"</code> for Practice 2 of 3)</td><td>string</td></tr><tr><td><code>details</code></td><td>Additional details about the session</td><td>string</td></tr><tr><td><code>placeholder</code></td><td>Whether this is a placeholder fixture</td><td>boolean</td></tr></tbody></table>

`group_id`, `aggregate_id`, `round_id`, `has_odds`, `has_premium_odds`, and `length` are not used in the Motorsport API.

#### The Fixtures endpoints

The Fixtures section has six endpoints:

| Endpoint                                         | Description                                  |
| ------------------------------------------------ | -------------------------------------------- |
| `GET /motorsport/fixtures`                       | All fixtures in your subscription            |
| `GET /motorsport/fixtures/{id}`                  | A single fixture by ID                       |
| `GET /motorsport/fixtures/multi/{ids}`           | Multiple fixtures by comma-separated IDs     |
| `GET /motorsport/fixtures/latest`                | All fixtures updated in the past 10 seconds  |
| `GET /motorsport/fixtures/date/{date}`           | All fixtures on a specific date (YYYY-MM-DD) |
| `GET /motorsport/fixtures/between/{start}/{end}` | All fixtures between two dates               |

#### Available includes

`sport` `stage` `league` `season` `venue` `state` `lineups` `participants` `metadata` `results` `latestLaps` `pitstops` `latestPitstops` `stints` `latestStints`

#### Retrieving fixtures

Get a single fixture by ID:

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

Get all fixtures for a season:

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

Get all fixtures on a specific date:

```http
GET https://api.sportmonks.com/v3/motorsport/fixtures/date/2025-03-16
?api_token={your_token}
```

Get all fixtures between two dates:

```http
GET https://api.sportmonks.com/v3/motorsport/fixtures/between/2025-03-14/2025-03-16
?api_token={your_token}
```

Get fixtures recently updated (for sync workflows):

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

#### Enriching fixtures

With state and venue:

```http
GET https://api.sportmonks.com/v3/motorsport/fixtures/19408487
?api_token={your_token}&include=state;venue
```

With results and lineups:

```http
GET https://api.sportmonks.com/v3/motorsport/fixtures/19408487
?api_token={your_token}&include=results;lineups.driver
```

With session metadata (lap count, fastest lap, race distance):

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

The `metadata` include returns session-level data typed by ID. The confirmed fixture metadata types are:

<table data-search="false"><thead><tr><th>ID</th><th>Developer Name</th><th>Description</th></tr></thead><tbody><tr><td><code>9737</code></td><td><code>IS_QUALIFICATION</code></td><td>Whether the session is part of a qualifying segment</td></tr><tr><td><code>9734</code></td><td><code>SPRINT_RACE</code></td><td>Whether the session is a sprint race with sprint points</td></tr><tr><td><code>164</code></td><td><code>HAS_STANDING</code></td><td>Whether the session contributes to championship standings</td></tr><tr><td><code>172</code></td><td><code>SPLIT_POINTS_RULE</code></td><td>Whether the half points rule applies</td></tr><tr><td><code>9736</code></td><td><code>CURRENT_LAP</code></td><td>Current lap number (live sessions)</td></tr><tr><td><code>105427</code></td><td><code>TOTAL_LAPS</code></td><td>Total lap count for the session</td></tr><tr><td><code>9716</code></td><td><code>FASTEST_LAP</code></td><td>Fastest lap time and lap number</td></tr><tr><td><code>114509</code></td><td><code>RACE_DISTANCE</code></td><td>Race distance in kilometres</td></tr><tr><td><code>110619</code></td><td><code>LEGACY_ID</code></td><td>The v1 stage ID for migration purposes</td></tr></tbody></table>

Match metadata entries by their `type_id` to identify which value you are reading.

#### Working with the data

**Get a fixture with full session context**

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

```javascript
const API_TOKEN = 'your_token';

async function getFixture(fixtureId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/fixtures/${fixtureId}
     ?api_token=${API_TOKEN}&include=state;venue;metadata`
  );
  const { data } = await response.json();
  return data;
}
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

API_TOKEN = "your_token"

def get_fixture(fixture_id):
    url = f"https://api.sportmonks.com/v3/motorsport/fixtures/{fixture_id}"
    params = {
        "api_token": API_TOKEN,
        "include": "state;venue;metadata"
    }
    response = requests.get(url, params=params)
    return response.json()["data"]

fixture = get_fixture(19408487)
print(f"{fixture['name']} at {fixture['venue']['name']} - state_id: {fixture['state_id']}")
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
function getFixture(string $apiToken, int $fixtureId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/fixtures/{$fixtureId}
            ?api_token={$apiToken}&include=state;venue;metadata";
    $response = json_decode(file_get_contents($url), true);
    return $response['data'];
}
```

{% endtab %}
{% endtabs %}

**Read a metadata value by developer name**

```python
METADATA_DEVELOPER_NAMES = {
    9736: "CURRENT_LAP",
    105427: "TOTAL_LAPS",
    9716: "FASTEST_LAP",
    114509: "RACE_DISTANCE",
    164: "HAS_STANDING",
    9734: "SPRINT_RACE",
}

def get_metadata_value(fixture, developer_name):
    for entry in fixture.get("metadata", []):
        if METADATA_DEVELOPER_NAMES.get(entry["type_id"]) == developer_name:
            return entry.get("value")
    return None

total_laps = get_metadata_value(fixture, "TOTAL_LAPS")
fastest_lap = get_metadata_value(fixture, "FASTEST_LAP")
```

```javascript
const METADATA_TYPE_IDS = {
  CURRENT_LAP: 9736,
  TOTAL_LAPS: 105427,
  FASTEST_LAP: 9716,
  RACE_DISTANCE: 114509,
  HAS_STANDING: 164,
  SPRINT_RACE: 9734,
};

function getMetadataValue(fixture, developerName) {
  const typeId = METADATA_TYPE_IDS[developerName];
  const entry = fixture.metadata?.find(m => m.type_id === typeId);
  return entry?.value ?? null;
}

const totalLaps = getMetadataValue(fixture, 'TOTAL_LAPS');
const fastestLap = getMetadataValue(fixture, 'FASTEST_LAP');
```

**Get all fixtures for a race weekend**

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

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

{% endtab %}

{% tab title="Python" %}

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

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}
{% endtabs %}

**Detect a sprint weekend**

```python
def is_sprint_weekend(stage_id):
    sessions = get_weekend_sessions(stage_id)
    session_names = [s["name"] for s in sessions]
    return "Sprint" in session_names
```

```javascript
async function isSprintWeekend(stageId) {
  const sessions = await getWeekendSessions(stageId);
  return sessions.some(s => s.name === 'Sprint');
}
```

#### Understanding the `leg` field

The `leg` field encodes a session's position within its session type:

| `leg` value | Meaning                                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| `"1/3"`     | Practice 1 of 3                                                                                         |
| `"2/3"`     | Practice 2 of 3                                                                                         |
| `"3/3"`     | Practice 3 of 3 (or Qualifying 3 of 3)                                                                  |
| `"1/1"`     | A single session of its type (Race, or Practice 1 when sprint weekend replaces other practice sessions) |

On a standard weekend, Practice 1 returns `"1/3"`. On a sprint weekend where practice sessions are reduced, Practice 1 returns `"1/1"` since there are no further practice sessions of that type.

#### Common pitfalls

**Using `GET All Fixtures` without a filter.** This returns your entire subscription, which can be thousands of records across all seasons. Always scope your request with `fixtureSeasons`, `fixtureStages`, or a date-based endpoint.

**Reading `length` for lap count.** The `length` field is listed as currently unused in the Motorsport API. Use the `TOTAL_LAPS` metadata type (ID `105427`) via `&include=metadata` for the lap count instead.

**Assuming `result_info` is populated.** `result_info` is only filled after a session has finished. For live race position data, use `&include=results` or `&include=lineups.details`.

**Treating `leg` as a round number.** `leg` is the session's position within its own session type, not the round number within the season. Use `stage.sort_order` for the round number.

**`group_id`, `aggregate_id`, and `round_id` are not used.** These fields exist for cross-sport compatibility but will always be null in motorsport responses.

#### Common errors

| Status | Likely cause                                                   |
| ------ | -------------------------------------------------------------- |
| `401`  | Missing or invalid `api_token`                                 |
| `404`  | The `fixture_id` does not exist or is not in your subscription |
| `422`  | Query complexity exceeded - reduce nested includes             |

#### See also

**Related tutorials**

* [Session states](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/live-data/session-states)
* [Retrieving results](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/retrieving-results)
* [Lineups](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/enrich-your-response/lineups)
* [Stages](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/schedule-and-calendar/stages)
* [Live sessions](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/live-data/live-sessions)

**Reference**

* [Fixture entity](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/fixture.md)
* [Metadata and Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference)
* [Results and Live Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/results-and-live-data-type-reference)

#### FAQ

**What is the difference between a fixture and a livescore?** A fixture is a session at any point in time: past, present, or future. A livescore is the same data filtered to a 15-minute active window around a session. Use livescores for real-time polling and fixtures for everything else.

**How do I find a fixture ID if I only know the race date?** Use `GET /motorsport/fixtures/date/{YYYY-MM-DD}` or `GET /motorsport/fixtures/between/{start}/{end}` with a date range covering the race weekend, then filter by `name` for the specific session type.

**How do I know if a fixture has been updated recently?** Use `GET /motorsport/fixtures/latest` which returns all fixtures updated in the past 10 seconds. This is the recommended approach for keeping a local database in sync without re-fetching the full dataset.

**Can I retrieve multiple specific fixtures in one call?** Yes. Use `GET /motorsport/fixtures/multi/{ids}` with a comma-separated list of fixture IDs.

**How do I tell if a session counts towards the championship standings?** Include `metadata` and check the `HAS_STANDING` type (ID `164`). A value of `true` means the session results contribute to the driver and constructor championships.


---

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