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_atWithout 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_pathThis 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_pathThis 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:
Working with the data
Selecting fields on a nested driver lineup
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
Related tutorials
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.
Last updated
Was this helpful?