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:

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

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.

Please note that set operations cannot be used as a wildcard for substring searches. For example, filters[]=+video_cdn_trace:fas cannot be used to return views with CDN traces that contain fastly.

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:mobile

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.

# Views from US AND went through fastly
filters[]=country:US
filters[]=+video_cdn_trace:fastly

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

# Views from US OR Canada
filters[]=country:US
filters[]=country:CA

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

# Views NOT from US AND NOT from Canada
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]  # Invalid

✅ Correct:

filters[]=+video_cdn_trace:fastly    # Valid

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

filters[]=video_cdn_trace:fastly  # Invalid

✅ Use trace or set operator syntax with trace dimensions:

filters[]=video_cdn_trace:[fastly]  # Exact match
filters[]=+video_cdn_trace:fastly   # Contains check

URL Encoding

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

# Single filter
/metrics?filters[]=country:US

# Multiple filters
/metrics?filters[]=country:US&filters[]=+tags:beta&filters[]=video_cdn_trace:[fastly,akamai]

# URL encoded
/metrics?filters%5B%5D=country%3AUS&filters%5B%5D=%2Btags%3Abeta&filters%5B%5D=video_cdn_trace%3A%5Bfastly%2Cakamai%5D

Here's an example of how you can URL encode the filter params using JavaScript:

// Example filters
const filters = [
  "country:US",
  "+tags:beta",
  "video_cdn_trace:[fastly,akamai]"
];

// Use URLSearchParams to build query string
const params = new URLSearchParams();
filters.forEach(f => params.append("filters[]", f));

// Full URL
const url = `/metrics?${params.toString()}`;

console.log(url);
// /metrics?filters%5B%5D=country%3AUS&filters%5B%5D=%2Btags%3Abeta&filters%5B%5D=video_cdn_trace%3A%5Bfastly%2Cakamai%5D

Common Use Cases

Analytics and Debugging

Find problematic CDN paths:

# Views that went through cloudflare but not fastly
filters[]=-video_cdn_trace:fastly
filters[]=+video_cdn_trace:cloudflare

Debug specific video delivery paths:

# Exact CDN sequence analysis
filters[]=video_cdn_trace:[fastly,akamai,cloudfront]

Performance Analysis

High-performance regions:

# Exclude slow CDN providers
filters[]=-video_cdn_trace:slow-cdn
filters[]=!operating_system:legacy

Mobile vs Desktop comparison:

# Mobile traffic analysis
filters[]=operating_system:ios
filters[]=operating_system:android

Content Filtering

Live vs VOD content:

# Exclude recorded content
filters[]=!content_type:recorded
filters[]=content_type:live

Platform-specific analysis:

# Web platform only, excluding mobile apps
filters[]=platform:web
filters[]=!platform:ios
filters[]=!platform:android

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)

Example error response:

{
  "error": "Sequence dimensions require bracket notation. Use video_cdn_trace:[value] instead of video_cdn_trace: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:

/metrics?timeframe[]=24:hours&filters[]=country:US&filters[]=+video_cdn_trace:akamai