> 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/drivers-and-teams/teams.md).

# Teams

This guide covers how to retrieve constructor team data, enrich it with season-specific details, and use it to build team profiles, constructor cards, and driver rosters.

#### When to use this

Use the Teams endpoints when you want to:

* Build a constructor team profile with logo, founding year, and country
* Get the driver roster for a team in a specific season
* Retrieve season-specific team details like chassis name, engine, and team colour
* Search for a team by name

#### The Team 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 team</td><td>integer</td></tr><tr><td><code>sport_id</code></td><td>Sport ID</td><td>integer</td></tr><tr><td><code>country_id</code></td><td>Country of the team</td><td>integer</td></tr><tr><td><code>gender</code></td><td>Gender of the team</td><td>string</td></tr><tr><td><code>name</code></td><td>Full team name</td><td>string</td></tr><tr><td><code>short_code</code></td><td>Short code of the team</td><td>string</td></tr><tr><td><code>image_path</code></td><td>URL to the team logo</td><td>string</td></tr><tr><td><code>founded</code></td><td>Year the team was founded</td><td>integer</td></tr><tr><td><code>type</code></td><td>Team type</td><td>string</td></tr><tr><td><code>placeholder</code></td><td>Whether this is a placeholder team</td><td>boolean</td></tr><tr><td><code>last_played_at</code></td><td>Date and time of the team's last attended session</td><td>integer</td></tr></tbody></table>

`venue_id` is not used in the Motorsport API.

#### Available includes

`sport` `country` `drivers` `latest` `upcoming` `seasons` `seasonDetails` `seasonDrivers`

#### Retrieving teams

Get all teams in your subscription:

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

Get a single team by ID:

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

Search teams by name:

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

Filter teams by country:

```http
GET https://api.sportmonks.com/v3/motorsport/teams
?api_token={your_token}&filters=teamCountries:{country_id}
```

#### Season-specific team data

The base team entity returns static information that does not change between seasons. Season-specific data - chassis name, engine, team colour, team lead, and the season name and logo the team used - is available via `seasonDetails`:

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

The confirmed `seasonDetails` types are:

<table data-search="false"><thead><tr><th>ID</th><th>Developer Name</th><th>Description</th></tr></thead><tbody><tr><td><code>109854</code></td><td><code>ENGINE</code></td><td>Engine name</td></tr><tr><td><code>109855</code></td><td><code>CHASSIS</code></td><td>Chassis name</td></tr><tr><td><code>109856</code></td><td><code>TEAM_COLOR</code></td><td>Team colour as a hex code</td></tr><tr><td><code>109857</code></td><td><code>TEAM_LEAD</code></td><td>Team principal name</td></tr><tr><td><code>109858</code></td><td><code>TECHNICAL_LEAD</code></td><td>Technical director name</td></tr><tr><td><code>109861</code></td><td><code>TEAM_NAME</code></td><td>Name the team used during this season</td></tr><tr><td><code>109862</code></td><td><code>TEAM_IMAGE</code></td><td>Logo URL the team used during this season</td></tr><tr><td><code>110619</code></td><td><code>LEGACY_ID</code></td><td>The v1 team ID for migration purposes</td></tr></tbody></table>

Note that `seasonDetails` uses a different include name than `metadata`. Team season data is accessed via `seasonDetails`, not `metadata`.

#### Driver roster

To get the current driver roster for a team:

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

To get the driver roster for a specific season:

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

`drivers` returns the current driver associations. `seasonDrivers` returns driver assignments per season, which is the right choice when building historical rosters or showing which drivers raced for the team in a given year.

#### Working with the data

**Build a constructor team card**

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

```javascript
const API_TOKEN = 'your_token';

async function getTeamCard(teamId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/teams/${teamId}
     ?api_token=${API_TOKEN}&include=country;seasonDetails;drivers`
  );
  const { data: team } = await response.json();

  const seasonLookup = Object.fromEntries(
    (team.seasonDetails ?? []).map(s => [s.type_id, s.value])
  );

  return {
    name: team.name,
    shortCode: team.short_code,
    logo: team.image_path,
    country: team.country?.name ?? null,
    founded: team.founded,
    colour: seasonLookup[109856]?.color_code ?? null,
    chassis: seasonLookup[109855]?.chassis ?? null,
    engine: seasonLookup[109854]?.engine ?? null,
    teamLead: seasonLookup[109857]?.team_lead ?? null,
    drivers: (team.drivers ?? []).map(d => d.display_name),
  };
}
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

API_TOKEN = "your_token"

def get_team_card(team_id):
    url = f"https://api.sportmonks.com/v3/motorsport/teams/{team_id}"
    params = {
        "api_token": API_TOKEN,
        "include": "country;seasonDetails;drivers"
    }
    response = requests.get(url, params=params)
    team = response.json()["data"]

    season_lookup = {s["type_id"]: s["value"] for s in team.get("seasonDetails", [])}

    return {
        "name": team["name"],
        "short_code": team["short_code"],
        "logo": team["image_path"],
        "country": team["country"]["name"] if team.get("country") else None,
        "founded": team["founded"],
        "colour": season_lookup.get(109856, {}).get("color_code"),
        "chassis": season_lookup.get(109855, {}).get("chassis"),
        "engine": season_lookup.get(109854, {}).get("engine"),
        "team_lead": season_lookup.get(109857, {}).get("team_lead"),
        "drivers": [d["display_name"] for d in team.get("drivers", [])],
    }
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
function getTeamCard(string $apiToken, int $teamId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/teams/{$teamId}
            ?api_token={$apiToken}&include=country;seasonDetails;drivers";
    $team = json_decode(file_get_contents($url), true)['data'];

    $seasonLookup = [];
    foreach ($team['seasonDetails'] ?? [] as $s) {
        $seasonLookup[$s['type_id']] = $s['value'];
    }

    return [
        'name' => $team['name'],
        'short_code' => $team['short_code'],
        'logo' => $team['image_path'],
        'country' => $team['country']['name'] ?? null,
        'founded' => $team['founded'],
        'colour' => $seasonLookup[109856]['color_code'] ?? null,
        'chassis' => $seasonLookup[109855]['chassis'] ?? null,
        'engine' => $seasonLookup[109854]['engine'] ?? null,
        'team_lead' => $seasonLookup[109857]['team_lead'] ?? null,
        'drivers' => array_map(fn($d) => $d['display_name'], $team['drivers'] ?? []),
    ];
}
```

{% endtab %}
{% endtabs %}

**Get the season-by-season roster for a team**

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

```javascript
async function getHistoricalRoster(teamId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/teams/${teamId}
     ?api_token=${API_TOKEN}&include=seasonDrivers`
  );
  const { data } = await response.json();
  return data.seasonDrivers ?? [];
}
```

{% endtab %}

{% tab title="Python" %}

```python
def get_historical_roster(team_id):
    url = f"https://api.sportmonks.com/v3/motorsport/teams/{team_id}"
    params = {
        "api_token": API_TOKEN,
        "include": "seasonDrivers"
    }
    response = requests.get(url, params=params)
    team = response.json()["data"]
    return team.get("seasonDrivers", [])
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
const API_TOKEN = 'YOUR_TOKEN';
function get_historical_roster($teamId) {
    $url = "https://api.sportmonks.com/v3/motorsport/teams/" . $teamId;
    $params = [
        "api_token" => API_TOKEN,
        "include" => "seasonDrivers"
    ];
    $requestUrl = $url . "?" . http_build_query($params);
    $response = file_get_contents($requestUrl);
    if ($response === false) {
        return [];
    }
    $json = json_decode($response, true);
    $team = $json["data"] ?? [];
    return $team["seasonDrivers"] ?? [];
}
```

{% endtab %}
{% endtabs %}

**Search for a team**

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

```javascript
async function searchTeam(name) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/teams/search/
     ${encodeURIComponent(name)}?api_token=${API_TOKEN}`
  );
  const { data } = await response.json();
  return data;
}
```

{% endtab %}

{% tab title="Python" %}

```python
def search_team(name):
    url = f"https://api.sportmonks.com/v3/motorsport/teams/search/{name}"
    params = {"api_token": API_TOKEN}
    response = requests.get(url, params=params)
    return response.json()["data"]
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
const API_TOKEN = 'YOUR_TOKEN';
function search_team($name) {
    $encodedName = urlencode($name);
    $url = "https://api.sportmonks.com/v3/motorsport/teams/search/" . $encodedName;
    $params = [
        "api_token" => API_TOKEN
    ];
    $requestUrl = $url . "?" . http_build_query($params);
    $response = file_get_contents($requestUrl);
    if ($response === false) {
        return [];
    }
    $json = json_decode($response, true);
    return $json["data"] ?? [];
}
```

{% endtab %}
{% endtabs %}

#### Common pitfalls

**Using `metadata` to get season-specific team data.** Team season data uses `seasonDetails`, not `metadata`. Using `&include=metadata` on a team request will not return chassis, engine, or colour data.

**Treating `name` as the historical team name.** Constructor teams often race under different names in different seasons (e.g. a team may rebrand between years). `name` is the current entity name. Use `seasonDetails` with `TEAM_NAME` (ID `109861`) to get the name the team used in a specific season.

**Using `image_path` for historical seasons.** Similarly, `image_path` is the current logo. `TEAM_IMAGE` (ID `109862`) in `seasonDetails` gives the logo the team used in a specific season.

**`venue_id` is not used.** This field exists for cross-sport compatibility and is always null in motorsport responses.

**`drivers` returns current associations only.** For season-by-season driver history, use `seasonDrivers` instead.

#### Common errors

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

#### See also

**Related tutorials**

* [Drivers](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/drivers-and-teams/drivers)
* [Standings](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/standings)
* [Filter and select fields - Filtering](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/filter-and-select-fields/filtering)

**Reference**

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

#### FAQ

**How do I get the team colour for a UI element?** Include `seasonDetails` and read the `TEAM_COLOR` type (ID `109856`). The value object contains a `color_code` key with the hex colour string.

**What is the difference between `drivers` and `seasonDrivers`?** `drivers` returns the current driver assignments for the team. `seasonDrivers` returns driver assignments per season, including historical seasons. Use `seasonDrivers` for any feature that shows past driver-team relationships.

**How do I get the engine and chassis name?** Include `seasonDetails` and read `ENGINE` (ID `109854`) and `CHASSIS` (ID `109855`). These are season-specific and change year to year.

**Why does the team logo look different from what I see on official sources?** `image_path` returns the current team logo in the Sportmonks system. If you are building a historical feature, use `TEAM_IMAGE` (ID `109862`) from `seasonDetails` to get the logo the team used in that specific season.

**Can I get both drivers and season details in a single request?** Yes. Separate multiple includes with a semicolon: `&include=drivers;seasonDetails;country`.


---

# 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/drivers-and-teams/teams.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.