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:

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:

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:

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:

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

First Tab

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;
}

Python

PHP

Selecting fields on a nested driver lineup

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
  }));
}

Python

PHP

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, before relying on it.

See also

Reference

• Request options

• Filter and select fields

Related tutorials

• Filtering

• 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.

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.