> 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/filter-and-select-fields/selecting-fields.md).

# Selecting fields

This guide covers how to use `&select=` to trim the API response down to only the fields you need, on both the base entity and on includes.

#### The basics

By default, an endpoint returns every field defined on the base entity. If you only need a subset, `&select=` reduces response size and speeds up the request:

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

Without field selection, a fixture response includes every field: `id`, `sport_id`, `league_id`, `season_id`, `stage_id`, `state_id`, `venue_id`, `name`, `starting_at`, `result_info`, `leg`, `details`, `placeholder`, `starting_at_timestamp`, and more. With `&select=name,starting_at`, only those two fields are returned, alongside any fields the API automatically retains for technical reasons (such as relation keys needed to resolve includes).

#### Selecting fields on an include

Field selection also works on includes, using a colon after the include name:

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

This returns the full lineup structure, but each nested `driver` object only contains `display_name` and `image_path` instead of the full driver entity.

You can select fields on multiple includes in the same request by separating each with a semicolon:

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

This selects `display_name` and `image_path` on the driver, and `name` and `image_path` on the driver's country, in a single request.

#### Selecting on the base entity and an include together

Base entity selection and include field selection are independent and combine in the same request:

```http
GET https://api.sportmonks.com/v3/motorsport/fixtures/19408487
?api_token={your_token}
&select=name,starting_at
&include=lineups.driver:display_name
```

#### Working with the data

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

```javascript
const API_TOKEN = 'your_token';
const FIXTURE_ID = 19408487;

async function getLeanFixture() {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/fixtures/${FIXTURE_ID}?api_token=${API_TOKEN}&select=name,starting_at`
  );
  const { data } = await response.json();
  return data;
}
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

API_TOKEN = "your_token"
FIXTURE_ID = 19408487

def get_lean_fixture():
    url = f"https://api.sportmonks.com/v3/motorsport/fixtures/{FIXTURE_ID}"
    params = {
        "api_token": API_TOKEN,
        "select": "name,starting_at"
    }
    response = requests.get(url, params=params)
    return response.json()["data"]
```

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}
{% endtabs %}

**Selecting fields on a nested driver lineup**

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

```javascript
async function getLeanLineup() {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/fixtures/${FIXTURE_ID}?api_token=${API_TOKEN}&include=lineups.driver:display_name,image_path`
  );
  const { data } = await response.json();
  return data.lineups.map(entry => ({
    driverName: entry.driver.display_name,
    image: entry.driver.image_path
  }));
}
```

{% endtab %}

{% tab title="Python" %}

```python
def get_lean_lineup():
    url = f"https://api.sportmonks.com/v3/motorsport/fixtures/{FIXTURE_ID}"
    params = {
        "api_token": API_TOKEN,
        "include": "lineups.driver:display_name,image_path"
    }
    response = requests.get(url, params=params)
    fixture = response.json()["data"]
    return [
        {"driver_name": entry["driver"]["display_name"], "image": entry["driver"]["image_path"]}
        for entry in fixture["lineups"]
    ]
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

const API_TOKEN = 'YOUR_TOKEN';
const FIXTURE_ID = 'YOUR_FIXTURE_ID';

function get_lean_lineup() {
    $url = "https://api.sportmonks.com/v3/motorsport/fixtures/" . FIXTURE_ID;
    $params = [
        "api_token" => API_TOKEN,
        "include" => "lineups.driver:display_name,image_path"
    ];
    $requestUrl = $url . "?" . http_build_query($params);
    $response = file_get_contents($requestUrl);
    if ($response === false) {
        return [];
    }
    $data = json_decode($response, true);
    $fixture = $data["data"] ?? [];
    $lineups = $fixture["lineups"] ?? [];
    return array_map(function ($entry) {
        return [
            "driver_name" => $entry["driver"]["display_name"] ?? null,
            "image" => $entry["driver"]["image_path"] ?? null
        ];
    }, $lineups);
}
```

{% endtab %}
{% endtabs %}

#### Common pitfalls

**Expecting unselected relation fields to disappear entirely.** The API automatically keeps certain relation-key fields (like foreign key IDs) even when not explicitly selected, since they are needed to resolve the entity's structure. Field selection trims display data, not the underlying relational keys.

**Using a comma to separate includes instead of a semicolon.** Within `&select=`, fields are comma-separated. Across multiple includes in `&include=`, the separator is a semicolon. Mixing these up silently produces unexpected results rather than an error.

**Selecting a field that doesn't exist on the entity.** This does not raise an error in most cases. The field is simply absent from the response. Cross-check the field name against the entity's field list, such as the one on the [Fixture entity page](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities), before relying on it.

#### See also

**Reference**

* [Request options](https://docs.sportmonks.com/v3/motorsport-api/welcome/request-options)
* [Filter and select fields](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/filter-and-select-fields)

**Related tutorials**

* [Filtering](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/filter-and-select-fields/filtering)
* [How to Use Includes in the Motorsport API](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/enrich-your-response/how-to-use-includes-in-the-motorsport-api)

#### FAQ

**Does field selection reduce my query complexity score?** Field selection reduces payload size and response time, but query complexity is calculated based on which includes you request, not which fields you select within them. See [Query complexity](https://docs.sportmonks.com/v3/motorsport-api/welcome/query-complexity).

**Can I select fields on a doubly nested include, like `lineups.driver.country`?** Yes, as shown in the multi-include example above. Add `:field1,field2` after each include level you want to trim, separated by semicolons from any other include in the request.

**Is `&select=` required?** No. Omitting it returns the full set of fields for that entity. Use it when you know in advance which fields your application actually needs.


---

# 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/filter-and-select-fields/selecting-fields.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.