# Filtering

The API provides a generic system to apply filters on collections. Not all endpoints support filters. Please refer to the individual documentation of each endpoint for more information on the supported filters.

To filter a collection, simply add the `filters=[field]:[operator]:[value]` query parameter to the url of the endpoint and make sure to URL encode the value. Multiple filters may be specified by separating each filter by a semicolon.

{% hint style="info" %}

### Simple filter example

In this example we get all popular events where the `sport` is not `Tennis` or `Soccer`:

```bash
$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?filters=sport:nin:Tennis,Soccer'
```

You can combine multiple filters by separating them with a semicolon. For example if you wanted to get all popular `Soccer` events except the Norwegian games you would do:

```bash
$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?filters=sport:eq:Soccer;country:neq:Norway'
```

{% endhint %}

## OR filtering

The above example demonstrates combining multiple filters using the `AND` filtering logic. If you want to apply an `OR` logic, you can use the `|` separator between multiple filters.

{% hint style="info" %}

### OR filter example

In this example we get all popular events where the `sport` is `Soccer` **or** the league is `NBA`:

```bash
$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?filters=sport:eq:Soccer|league:eq:NBA'
```

{% endhint %}

Notice that `AND` and `OR` filters can be combined in the same request. In that case, the `OR` filters are grouped together to a nested clause.

{% hint style="info" %}

### AND and OR filters combined

In this example we get all popular events where the `status` is `live` **and** (`sport` is `Soccer` **or** `league` is `NBA`):

```bash
$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?filters=status:eq:live;sport:eq:Soccer|league:eq:NBA'
```

{% endhint %}

## Filtering fields

If filtering is available for an endpoint, then the supported filtering fields are indicated in the documentation of that endpoint.

{% hint style="danger" %}

### Field types

Notice that an error will be returned if the provided filter value does not match the type of the underlying field.

For example if you try to filter a numeric field with a string value:

```bash
$ curl --request GET \\
  --url 'https://api.vaix.ai/api/crm/predictions/retention?operator=luckybus&filters=apds_last_30:gt:invalid' \\
  --header 'Content-Type: application/json'
```

you will get a **400 Bad Request** response:

```json
{
    "error": "invalid value for filters",
    "status": "error"
}
```

{% endhint %}

## Filtering operators

The following operators are supported by the API:

| Operator | Description                                                                                                                                         |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `in`     | Returns entries where the field **is equal to one of** the provided values. The values should be comma separated, e.g. `sport:in:soccer,rugby`      |
| `nin`    | Returns entries where the field **is not equal to any of** the provided values. The values should be comma separated, e.g. `sport:nin:soccer,rugby` |
| `eq`     | Returns entries where the field is **equal to** the value, e.g. `country:eq:germany`                                                                |
| `neq`    | Returns entries where the field is **not equal to** the value, e.g. `country:neq:germany`                                                           |
| `gt`     | Returns entries where the field is **greater than** the value, e.g. `churn_score:gt:0.5`                                                            |
| `gte`    | Returns entries where the field is **greater or equal to** the value, `churn_score:gte:0.5`                                                         |
| `lt`     | Returns entries where the field is **less than** the value, e.g. `churn_score:lt:0.5`                                                               |
| `lte`    | Returns entries where the field is **less or equal to** the value, e.g. `churn_score:lte:0.5`                                                       |

## Filters on array fields

Currently only `in`, `nin` filters are supported for fields that contain array values like the `participants` of an event. Providing a different filtering operator for such a field will result in a **400 Bad Request** response.

## Dynamic filtering

Some endpoints support a dynamic filtering functionality. In those cases, the filter's value does not need to be provided in the request parameters, but it will be dynamically calculated during the request's execution. These filters are usually user-related and for them to work the `user` query parameter must also be specified.

In the following example, we get events that are popular in the user's country.

```bash
$ curl --request GET \\
  --url 'https://api.vaix.ai/api/sports/events/popular?user=123&dynamic_filters=user_country' \\
  --header 'Content-Type: application/json'
```

## Ranking filtering

Some endpoints support a ranking filtering functionality. In those cases, an extra filter is dynamically added to the request, where its value will be calculated by ranking the given entity and getting the top `count` values out of it. Notice that for ranking recommended-related entities, the `user` query parameter must also be specified.

The expected format is a comma separated list of the form `entity:ranking` where `entity` corresponds to one of the supported entities and `ranking` is a single integer indicating the exact ranking position of the entity to use for filtering.

For example a ranking filter of the form `game_studio_recommended:1` would filter the endpoint's results to return only games which are designed by the top recommended game studio of the current user.

For a multi-ranking example, `game_studio_recommended:1,game_category_popular:1` would apply the above filter and on top of that, it will only include games from the most popular game category.

In the following example, we get recommended games which all belong to the user's most recommended game studio.

```bash
$ curl --request GET \\
  --url 'https://api.vaix.ai/api/casino/games/recommended?user=123&ranking_filter=game_studio_recommended:1' \\
  --header 'Content-Type: application/json'
```


---

# Agent Instructions: 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:

```
GET https://docs.sportradar.com/personalization/overview/using-the-api/filtering.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.