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>

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

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.

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.

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:

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]