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

# Filtering

This guide covers how to use `&filters=` to narrow down which records the API returns, and how static and dynamic filters differ.

#### The basics

Filtering controls which records come back, not which fields are on each record. For field-level control, see [Selecting fields](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/filter-and-select-fields/selecting-fields).

There are two kinds of filters:

**Static filters** are predefined and filter in one fixed way with no custom options. Not every endpoint has static filters.

**Dynamic filters** are entity-based. You name the entity you want to filter on and pass one or more IDs as the value:

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

`fixtureLeagues` is the filter name and `3468` is the league ID to filter on. Pass multiple values as a comma-separated list:

```http
GET https://api.sportmonks.com/v3/motorsport/fixtures
?api_token={your_token}&filters=fixtureLeagues:3468,3470
```

The general `&filters=` syntax is documented on [Request options](https://docs.sportmonks.com/v3/motorsport-api/welcome/request-options).

#### Available filters by entity

You can retrieve the full filter catalogue for your subscription at any time by calling:

```http
GET https://api.sportmonks.com/v3/my/filters/entity?api_token={your_token}
```

The motorsport entities and their confirmed dynamic filters are listed below.

**Fixtures**

<table data-search="false"><thead><tr><th>Filter</th><th>Filters by</th></tr></thead><tbody><tr><td><code>fixtureLeagues</code></td><td>League ID</td></tr><tr><td><code>fixtureSeasons</code></td><td>Season ID</td></tr><tr><td><code>fixtureStates</code></td><td>State ID</td></tr><tr><td><code>fixtureStages</code></td><td>Stage ID</td></tr><tr><td><code>venues</code></td><td>Venue ID</td></tr><tr><td><code>todaydate</code></td><td>Today's fixtures only</td></tr><tr><td><code>deleted</code></td><td>Soft-deleted fixtures</td></tr><tr><td><code>participantsearch</code></td><td>Driver or team name (string search)</td></tr></tbody></table>

**Drivers** (driver is an alias for the `player` entity, so player filters apply)

| Filter            | Filters by |
| ----------------- | ---------- |
| `playerCountries` | Country ID |
| `genders`         | Gender     |

**Teams**

| Filter          | Filters by |
| --------------- | ---------- |
| `teamCountries` | Country ID |
| `genders`       | Gender     |

**Laps**

| Filter       | Filters by |
| ------------ | ---------- |
| `lapLeagues` | League ID  |

**Lap details**

| Filter             | Filters by |
| ------------------ | ---------- |
| `lapdetailLeagues` | League ID  |
| `lapdetailTypes`   | Type ID    |

**Pitstops**

| Filter           | Filters by |
| ---------------- | ---------- |
| `pitstopLeagues` | League ID  |

**Pitstop details**

| Filter                 | Filters by |
| ---------------------- | ---------- |
| `pitstopdetailLeagues` | League ID  |
| `pitstopdetailTypes`   | Type ID    |

**Stints**

| Filter         | Filters by |
| -------------- | ---------- |
| `stintLeagues` | League ID  |

**Stint details**

| Filter               | Filters by |
| -------------------- | ---------- |
| `stintdetailLeagues` | League ID  |
| `stintdetailTypes`   | Type ID    |

**Standings**

| Filter            | Filters by |
| ----------------- | ---------- |
| `standingLeagues` | League ID  |
| `standingSeasons` | Season ID  |
| `standingGroups`  | Group ID   |
| `standingStages`  | Stage ID   |

**Seasons**

| Filter          | Filters by |
| --------------- | ---------- |
| `seasonLeagues` | League ID  |

**Leagues**

| Filter            | Filters by |
| ----------------- | ---------- |
| `leagueLeagues`   | League ID  |
| `leagueCountries` | Country ID |

**Stages**

| Filter         | Filters by |
| -------------- | ---------- |
| `stageLeagues` | League ID  |
| `stageSeasons` | Season ID  |
| `stageTypes`   | Type ID    |
| `stageStages`  | Stage ID   |

**Lineups**

| Filter          | Filters by |
| --------------- | ---------- |
| `lineupLeagues` | League ID  |
| `lineupTypes`   | Type ID    |
| `lineupPlayers` | Driver ID  |

**Lineup details**

| Filter                | Filters by |
| --------------------- | ---------- |
| `lineupdetailLeagues` | League ID  |
| `lineupdetailTypes`   | Type ID    |
| `lineupdetailPlayers` | Driver ID  |

**Metadata**

| Filter          | Filters by |
| --------------- | ---------- |
| `metadataTypes` | Type ID    |

#### Working with the data

**Filter fixtures by season**

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

```javascript
const API_TOKEN = 'your_token';

async function getFixturesBySeason(seasonId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/fixtures?api_token=${API_TOKEN}&filters=fixtureSeasons:${seasonId}`
  );
  const { data } = await response.json();
  return data;
}
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

API_TOKEN = "your_token"

def get_fixtures_by_season(season_id):
    url = "https://api.sportmonks.com/v3/motorsport/fixtures"
    params = {
        "api_token": API_TOKEN,
        "filters": f"fixtureSeasons:{season_id}"
    }
    response = requests.get(url, params=params)
    return response.json()["data"]
```

{% endtab %}

{% tab title="PHP" %}

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

{% endtab %}
{% endtabs %}

**Filter drivers by country**

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

```javascript
async function getDriversByCountry(countryId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/drivers?api_token=${API_TOKEN}&filters=playerCountries:${countryId}`
  );
  const { data } = await response.json();
  return data;
}
```

{% endtab %}

{% tab title="Python" %}

```python
def get_drivers_by_country(country_id):
    url = "https://api.sportmonks.com/v3/motorsport/drivers"
    params = {
        "api_token": API_TOKEN,
        "filters": f"playerCountries:{country_id}"
    }
    response = requests.get(url, params=params)
    return response.json()["data"]
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
function getDriversByCountry(string $apiToken, int $countryId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/drivers?api_token={$apiToken}&filters=playerCountries:{$countryId}";
    $response = json_decode(file_get_contents($url), true);
    return $response['data'];
}
```

{% endtab %}
{% endtabs %}

**Filter standings by season**

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

```javascript
async function getStandingsBySeason(seasonId) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/standings?api_token=${API_TOKEN}&filters=standingSeasons:${seasonId}`
  );
  const { data } = await response.json();
  return data;
}
```

{% endtab %}

{% tab title="Python" %}

```python
def get_standings_by_season(season_id):
    url = "https://api.sportmonks.com/v3/motorsport/standings"
    params = {
        "api_token": API_TOKEN,
        "filters": f"standingSeasons:{season_id}"
    }
    response = requests.get(url, params=params)
    return response.json()["data"]
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
function getStandingsBySeason(string $apiToken, int $seasonId): array {
    $url = "https://api.sportmonks.com/v3/motorsport/standings?api_token={$apiToken}&filters=standingSeasons:{$seasonId}";
    $response = json_decode(file_get_contents($url), true);
    return $response['data'];
}
```

{% endtab %}
{% endtabs %}

**Combining filters with field selection**

Filtering and field selection are independent and can be used together:

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

#### Common pitfalls

**Using a driver filter name that doesn't exist.** Driver is an alias for the `player` entity in the Sportmonks data model, so driver filters use the `player` prefix: `playerCountries`, not `driverCountries`.

**Forgetting the colon syntax.** Dynamic filters use `filterName:value` inside the `filters` parameter. The outer parameter is `&filters=`; the colon separates the filter name from its value.

**Passing multiple values with a semicolon instead of a comma.** Multiple values for the same filter are comma-separated: `fixtureLeagues:3468,3470`. Semicolons are for separating multiple includes in `&include=`, not multiple filter values.

**Assuming every filter works on every endpoint.** `fixtureLeagues` only works on fixture-related endpoints. `lapLeagues` only works on lap endpoints. Check the table above and confirm against the endpoint's own documentation before building a request around a specific filter.

#### 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)
* [GET /v3/my/filters/entity](https://api.sportmonks.com/v3/my/filters/entity)

**Related tutorials**

* [Selecting fields](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/filter-and-select-fields/selecting-fields)

#### FAQ

**How do I find all available filters for my subscription?** Call `GET https://api.sportmonks.com/v3/my/filters/entity?api_token={your_token}`. This returns the full filter catalogue for every entity your subscription has access to.

**Why does filtering drivers use `playerCountries` instead of `driverCountries`?** Driver is an alias for the `player` entity in the Sportmonks data model. The underlying entity is `player`, so its filters use the `player` prefix. The same filter names used for football players apply to motorsport drivers.

**Can I stack multiple different filters in one request?** Yes. Separate them with a semicolon inside the `&filters=` value: `&filters=fixtureSeasons:25273;fixtureStates:5`. Each filter narrows the result set further.

**What is `deleted` used for on fixtures?** The `deleted` filter returns soft-deleted fixtures. This is useful for database sync workflows where you need to track fixtures that have been removed. See [How to keep your race data in sync](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-keep-your-race-data-in-sync) for the full sync pattern.


---

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