# Filter your Data

Filter Mux Data metrics and views with the `filters[]` query parameter. Use filters to narrow results by dimensions such as country, operating system, or CDN.

Mux Data queries can return more data than you need. Use the `filters[]` parameter when you want to narrow a query to specific views. For example, you can limit results to one country, one operating system, or one CDN.

The `filters[]` parameter allows you to filter your data using flexible syntax that supports different types of operations depending on the dimension type.

## Filter Syntax Overview

The basic format for all filters is:

`filters[]=<operation><dimension>:<value>`

- <operation> is the optional prefix that defines the type of filter.
  - Examples:
    - (none) → equals → `country:US`
    - `!` → not equals → `!country:US`
    - `+` → set contains → `+video_cdn_trace:fastly`
    - `-` → set omits → `-video_cdn_trace:cloudflare`
- <dimension> is the field or metric you want to filter on.
  - Examples: `country`, `operating_system`, `video_cdn_trace`
- **`:`** acts as the separator between the dimension and the value.
- <value> is the value you're comparing against.
  - Examples:
    - Scalar → `US`, `windows`
    - Trace → `[fastly,akamai]`
    - Empty trace → `[]`

## Supported Operations

### Scalar Operations

Scalar operations can be used with single-value dimensions or simple key-value pairs. Use these operations when you want to filter by an exact match or exclusion.

| Syntax | Operation | Example | Description |
| --- | --- | --- | --- |
| `dimension:value` | Equals | `filters[]=country:US` | Field equals value |
| `!dimension:value` | Not equals | `filters[]=!operating_system:windows` | Field does not equal value |

### Set Operations

Use for trace dimensions that can have multiple values in an ordered list. Use these operations when you want to check if a single value appears in the trace dimension.

| Syntax | Operation | Example | Description |
| --- | --- | --- | --- |
| `+dimension:value` | Has | `filters[]=+video_cdn_trace:fastly` | Set contains value |
| `-dimension:value` | Omits | `filters[]=-video_cdn_trace:cloudflare` | Set does NOT contain value |

### Trace Operations

Use for trace dimensions that can have multiple values in an ordered list. Use this operation when you want to filter for an exact, ordered match.

| Syntax | Operation | Example | Description |
| --- | --- | --- | --- |
| `dimension:[value1,value2]` | Equals | `filters[]=video_cdn_trace:[fastly,akamai]` | Trace equals exactly `[fastly, akamai]` |

## Practical Examples

### Scalar (Basic) Operations

Filter for views from the US:

```
filters[]=country:US
```

Exclude mobile operating systems:

```
filters[]=!operating_system:windows
```

### Set Operations

Find views with 'fastly' as a CDN value in the video_cdn_trace dimension.

```
filters[]=+video_cdn_trace:fastly
```

Exclude views that went through `cloudflare`:

```
filters[]=-video_cdn_trace:cloudflare
```

### Trace Operations

Find views that went through exactly `fastly` first, then `akamai`:

```
filters[]=video_cdn_trace:[fastly,akamai]
```

Find views where no CDN value was set:

```
filters[]=video_cdn_trace:[]
```

### Multiple Filters

You can combine multiple filters.

**Filters with different dimensions**

When you are combining filters with different dimensions they are combined with AND.

```
filters[]=country:US&filters[]=!operating_system:windows
```

You can also combine dimensions with the same dimension. These are combined with OR.

```
filters[]=country:US|country:CA
```

However, if you are combining filters with the same dimension value with a negated value, those are combined using AND.

```
filters[]=country:US&filters[]=!country:CA
```

### Value Formatting

- **Scalar (basic) values**: Plain strings (`country:US`)
- **Trace values**: Comma-separated values in brackets (`video_cdn_trace:[a,b,c]`)
- **Empty traces**: Use empty brackets (`video_cdn_trace:[]`)

## Common Errors

❌ **Don't use brackets with set operators:**

```
filters[]=+video_cdn_trace:[fastly]
```

✅ **Correct:**

```
filters[]=+video_cdn_trace:fastly
```

❌ **Don't use scalar operator syntax with trace dimensions:**

```
filters[]=country:[US]
```

✅ **Use trace or set operator syntax with trace dimensions:**

```
filters[]=video_cdn_trace:[fastly,akamai]
```

## URL Encoding

When using filters in URLs, remember to properly encode the parameters:

```javascript
const url = `https://api.example.com/data?filters=${encodeURIComponent(filters)}`;
```

## Common Use Cases

### Analytics and Debugging

#### Find problematic CDN paths:

```
filters[]=!video_cdn_trace:success
```

#### Debug specific video delivery paths:

```
filters[]=video_cdn_trace:[fastly,akamai]
```

### Performance Analysis

#### High-performance regions:

```
filters[]=region:US
```

#### Mobile vs Desktop comparison:

```
filters[]=operating_system:mobile|operating_system:desktop
```

### Content Filtering

#### Live vs VOD content:

```
filters[]=content_type:live
```

#### Platform-specific analysis:

```
filters[]=platform:android|platform:ios
```

## Error Handling

The API will return validation errors for:

- Invalid dimension names
- Incorrect operator usage for dimension type
- Malformed values (e.g., mismatched brackets, quotes)
- Invalid operator combinations (e.g., `!+dimension:value`)

## Advanced Tips

### Testing Your Filters

To ensure your filters are working as expected, it can be helpful to limit the dataset you're working with. For that reason, you may wish to test your filters with a small date range first:

```
filters[]=date:[2023-01-01,2023-01-07]
```
