MP2 (Media Protection Platform)
Advanced
Playback stats

Playback Statistics

Fastevo MP2 provides comprehensive playback statistics with advanced filtering capabilities. This guide will help you understand how to retrieve and interpret these statistics using powerful filters to analyze viewer behavior and content performance.

Overview

Playback statistics can be queried at the project level with extensive filtering options. The statistics include various metrics such as total impressions, playbacks, play time, and demographic breakdowns. The advanced filtering system allows you to segment your analytics data by multiple dimensions simultaneously.

Retrieving Project Playback Statistics with Advanced Filters

The project statistics endpoint now supports advanced filtering capabilities that allow you to analyze playback data across multiple dimensions.

Endpoint

GET https://api.fastevo.net/api/v1/projects/{projectId}/mediaprotection/stats/general

Required Query Parameters

  • startDate (string): The start date for the statistics query (ISO 8601 format)
  • endDate (string): The end date for the statistics query (ISO 8601 format)

Advanced Filter Parameters

The endpoint supports numerous optional filter parameters to segment your data:

Content and Protection Filters

  • contentId (string): Filter by specific content ID (MongoDB ObjectId format)
    • Example: 68267a1db67be4c5088a008c
    • Supports comma-separated values: 68267a1db67be4c5088a008c,68267a1db67be4c5088a008d
  • contentType (string): Filter by content type
    • Allowed values: video, image
    • Supports comma-separated values: video,image
  • protectionLevel (string): Filter by DRM protection level
    • Allowed values: standard, enhanced, adaptive, qualityDependant
    • Supports comma-separated values: standard,enhanced, adaptive,enhanced

Viewer and Device Filters

  • viewerIdentifier (string): Filter by specific viewer ID
    • Example: 30332, user@example.com
    • Supports comma-separated values: 30332,30333,30334
  • viewerTags (string/array): Filter by viewer tags
    • Format: Comma-separated string or array
    • Example: premium,verified or ["premium", "verified"]
    • Note: Matches sessions that contain ANY of the provided tags
  • device (string): Filter by device type
    • Common values: mobile, desktop, tablet, iPad, iPhone, etc.
    • Supports comma-separated values: iPad,iPhone,mobile
  • operatingSystem (string): Filter by operating system
    • Common values: iOS, Android, Windows, macOS, Linux
    • Supports comma-separated values: iOS,Android
  • clientType (string): Filter by client type
    • Allowed values: webBrowser, mobileApp, smartTV, other
    • Supports comma-separated values: webBrowser,mobileApp
  • clientVersion (string): Filter by specific client version
    • Example: v1.1.2
    • Supports comma-separated values: v1.1.2,v1.1.3,v1.2.0

Location Filters

Location filters use ISO country codes and support multiple values:

  • location.country (string): Filter by country using 2-letter ISO code
    • Format: ISO 3166-1 alpha-2 code (uppercase)
    • Examples: US (United States), AU (Australia), GB (United Kingdom), JP (Japan)
    • Supports comma-separated values: US,CA,MX (North America), GB,FR,DE (Europe)
  • location.region (string): Filter by region/state
    • Examples: NSW (New South Wales), CA (California), ON (Ontario)
    • Supports comma-separated values: CA,NY,TX (multiple US states)
  • location.city (string): Filter by city name
    • Examples: Sydney, New York, London, Tokyo
    • Supports comma-separated values: Sydney,Melbourne,Brisbane
  • location.zipCode (string): Filter by ZIP/postal code
    • Examples: 2040, 10001, M5V 3A8
    • Supports comma-separated values: 10001,10002,10003

Security Filters

  • ipClassification (string): Filter by IP category classification
    • Allowed values: residential, business, hosting, education, mobile, vpn, proxy, tor, unknown
    • Supports comma-separated values: residential,business, vpn,proxy,tor
  • isIpAssociatedWithMaliciousEventsRecently (string): Filter by malicious IP status
    • Format: String "true" or "false" (will be converted to boolean)
    • Example: isIpAssociatedWithMaliciousEventsRecently=true
    • Note: Does not support comma-separated values (boolean field)
  • appliedMediaProtectionSiemRule (string): Filter by applied SIEM rule ID (MongoDB ObjectId format)
    • Example: 507f1f77bcf86cd799439011
    • Supports comma-separated values: 507f1f77bcf86cd799439011,507f1f77bcf86cd799439012

Example Requests

Basic Request

GET https://api.fastevo.net/api/v1/projects/{projectId}/mediaprotection/stats/general?startDate=2025-01-01T00:00:00Z&endDate=2025-06-01T00:00:00Z

Request with Content Filters

GET https://api.fastevo.net/api/v1/projects/{projectId}/mediaprotection/stats/general?
  startDate=2025-01-01T00:00:00Z&
  endDate=2025-06-01T00:00:00Z&
  contentType=video&
  protectionLevel=enhanced

Request for Specific Content

GET https://api.fastevo.net/api/v1/projects/{projectId}/mediaprotection/stats/general?
  startDate=2025-01-01T00:00:00Z&
  endDate=2025-06-01T00:00:00Z&
  contentId=507f1f77bcf86cd799439011

Request with Viewer Segmentation

GET https://api.fastevo.net/api/v1/projects/{projectId}/mediaprotection/stats/general?
  startDate=2025-01-01T00:00:00Z&
  endDate=2025-06-01T00:00:00Z&
  viewerTags=premium,verified&
  device=mobile&
  operatingSystem=iOS

Request with Location Filters

GET https://api.fastevo.net/api/v1/projects/{projectId}/mediaprotection/stats/general?
  startDate=2025-01-01T00:00:00Z&
  endDate=2025-06-01T00:00:00Z&
  location.country=US&
  location.region=California&
  location.city=San Francisco

Request with Multiple Countries

GET https://api.fastevo.net/api/v1/projects/{projectId}/mediaprotection/stats/general?
  startDate=2025-01-01T00:00:00Z&
  endDate=2025-06-01T00:00:00Z&
  location.country=US,CA,MX&
  contentType=video

Request with Multiple Devices and Operating Systems

GET https://api.fastevo.net/api/v1/projects/{projectId}/mediaprotection/stats/general?
  startDate=2025-01-01T00:00:00Z&
  endDate=2025-06-01T00:00:00Z&
  device=iPad,iPhone&
  operatingSystem=iOS,iPadOS

Request with Security Filters

GET https://api.fastevo.net/api/v1/projects/{projectId}/mediaprotection/stats/general?
  startDate=2025-01-01T00:00:00Z&
  endDate=2025-06-01T00:00:00Z&
  isIpAssociatedWithMaliciousEventsRecently=false&
  ipClassification=residential

API Response

The API returns aggregated statistics based on your filter criteria.

Example Response

{
  "success": true,
  "data": {
    "totalImpressions": 15420,
    "totalPlaybacks": 12350,
    "totalPlayTimeInSeconds": 987650,
    "totalPauseTimeInSeconds": 45230,
    "averagePlayTimeInSeconds": 79.97,
    "averagePauseTimeInSeconds": 3.66,
    "averageCompletionPercent": 85.3,
    "impressionsPerCountry": [
      {
        "country": "United States",
        "count": 8520
      },
      {
        "country": "Canada",
        "count": 3200
      }
    ],
    "impressionsPerOsAndVersion": [
      {
        "osAndVersion": "iOS 17.5",
        "count": 4200
      },
      {
        "osAndVersion": "Android 14",
        "count": 3800
      }
    ],
    "impressionsPerOS": [
      {
        "os": "iOS",
        "count": 7800
      },
      {
        "os": "Android",
        "count": 5620
      }
    ],
    "impressionsPerDevice": [
      {
        "device": "mobile",
        "count": 9800
      },
      {
        "device": "desktop",
        "count": 4200
      }
    ],
    "impressionsPerBrowser": [
      {
        "browser": "Safari",
        "count": 6200
      },
      {
        "browser": "Chrome",
        "count": 5800
      }
    ]
  }
}

Response Fields Explained

  • totalImpressions: Total number of unique playback sessions matching your filters
  • totalPlaybacks: Number of sessions that achieved minimum playback time
  • totalPlayTimeInSeconds: Cumulative play time across all sessions
  • totalPauseTimeInSeconds: Cumulative pause time across all sessions
  • averagePlayTimeInSeconds: Average play duration per session
  • averagePauseTimeInSeconds: Average pause duration per session
  • averageCompletionPercent: Average percentage of content completed
  • impressionsPerCountry: Breakdown of impressions by country
  • impressionsPerOsAndVersion: Detailed OS version breakdown
  • impressionsPerOS: High-level OS breakdown
  • impressionsPerDevice: Device type distribution
  • impressionsPerBrowser: Browser usage statistics

Use Cases for Advanced Filters

1. Geographic Performance Analysis

Analyze content performance in specific regions:

# Single region
?location.country=US&location.region=California
 
# Multiple countries in a region
?location.country=US,CA,MX  # North America
 
# Multiple cities
?location.city=Sydney,Melbourne,Brisbane  # Major Australian cities

2. Premium User Analytics

Track engagement for premium subscribers:

?viewerTags=premium,active

3. Mobile vs Desktop Analysis

Compare performance across platforms:

?device=mobile&operatingSystem=iOS

4. Security Monitoring

Identify suspicious activity patterns:

?isIpAssociatedWithMaliciousEventsRecently=true

5. Content Type Performance

Compare video vs image content:

?contentType=video&protectionLevel=enhanced

6. Individual Content Analytics

Analyze performance for a specific content item:

?contentId=507f1f77bcf86cd799439011

Filter Format Details

Comma-Separated Values for OR Queries

Most string-based filters support comma-separated values to filter by multiple options using OR logic. This powerful feature allows you to query data across multiple values in a single request.

How it works:

  • Separate multiple values with commas (no spaces needed)
  • The filter will match records that have ANY of the specified values
  • Example: location.country=US,CA,MX matches sessions from US OR Canada OR Mexico

Supported fields:

  • All location filters (location.country, location.region, location.city, location.zipCode)
  • Device and client filters (device, operatingSystem, clientType, clientVersion)
  • Content filters (contentId, contentType, protectionLevel)
  • Security filters (ipClassification, appliedMediaProtectionSiemRule)
  • Viewer filters (viewerIdentifier)

Special cases:

  • viewerTags already supports comma-separated values by design
  • isIpAssociatedWithMaliciousEventsRecently does not support multiple values (boolean)

Understanding Location Filters

Location filters must use specific formats that match how location data is stored:

  • Country: Use uppercase 2-letter ISO codes
    • ✅ Correct: location.country=AU
    • ❌ Incorrect: location.country=Australia, location.country=au
  • Region: Use standard state/province abbreviations
    • Example: location.region=NSW (New South Wales)
    • Example: location.region=CA (California)
  • City: Use exact city names with proper capitalization
    • Example: location.city=Sydney
    • Example: location.city=New York
  • ZIP Code: Use exact postal codes
    • Example: location.zipCode=2040
    • Example: location.zipCode=10001

Device and Client Information

When filtering by device or client information:

  • Device: Common values include specific device models
    • Examples: device=iPad, device=iPhone, device=mobile, device=desktop
  • Operating System: Use exact OS names
    • Examples: operatingSystem=iOS, operatingSystem=Android, operatingSystem=macOS
  • Client Type: Predefined client categories
    • Examples: clientType=webBrowser, clientType=mobileApp, clientType=smartTV

Content and Protection Filters

  • Content Type: Filter by media type
    • Examples: contentType=video, contentType=image
  • Protection Level: DRM protection levels
    • Examples: protectionLevel=standard, protectionLevel=enhanced, protectionLevel=adaptive

Viewer Information

  • Viewer Identifier: Exact match on viewer ID
    • Example: viewerIdentifier=30332
    • Example: viewerIdentifier=user@example.com
  • Viewer Tags: Match any of the provided tags
    • Example: viewerTags=premium,verified (matches viewers with either tag)

Security Classifications

  • IP Classification: Categories of IP addresses
    • Examples: ipClassification=residential, ipClassification=business, ipClassification=vpn
  • Malicious IP Status: Boolean flag as string
    • Example: isIpAssociatedWithMaliciousEventsRecently=true
    • Example: isIpAssociatedWithMaliciousEventsRecently=false

Common Location Filter Examples

Filter by Country

# Single country - Australia
?location.country=AU
 
# Multiple countries - North America
?location.country=US,CA,MX
 
# Multiple countries - English-speaking
?location.country=US,GB,AU,CA,NZ
 
# Multiple countries - Europe
?location.country=GB,FR,DE,IT,ES

Filter by Region/State

# New South Wales, Australia
?location.country=AU&location.region=NSW
 
# California, USA
?location.country=US&location.region=CA
 
# Ontario, Canada
?location.country=CA&location.region=ON

Filter by City

# Sydney, Australia
?location.country=AU&location.city=Sydney
 
# New York, USA
?location.country=US&location.city=New York
 
# Toronto, Canada
?location.country=CA&location.city=Toronto

Working with Array Filters

The viewerTags filter supports multiple formats:

Comma-separated string

?viewerTags=premium,verified,beta

URL-encoded array (for programmatic use)

?viewerTags[]=premium&viewerTags[]=verified&viewerTags[]=beta

The filter will match sessions that contain any of the specified tags (OR operation).

Boolean Filter Format

Boolean filters must be passed as strings:

# Correct
?isIpAssociatedWithMaliciousEventsRecently=true
?isIpAssociatedWithMaliciousEventsRecently=false
 
# Incorrect (will not work)
?isIpAssociatedWithMaliciousEventsRecently=1
?isIpAssociatedWithMaliciousEventsRecently=yes
💡

Pro Tip: Combine multiple filters to create powerful analytics queries. You can also use comma-separated values to expand your queries. For example:

  • Analyze premium users across multiple countries: viewerTags=premium&location.country=US,CA,GB
  • Track performance on Apple devices: device=iPad,iPhone,AppleTV
  • Monitor suspicious activity from multiple IP types: ipClassification=vpn,proxy,tor

Best Practices

  1. Date Range Selection: Choose appropriate date ranges to ensure statistically significant data
  2. Filter Combinations: Start with broad filters and progressively narrow down to identify trends
  3. Performance Considerations: More specific filters generally result in faster query response times
  4. Data Privacy: Ensure compliance with privacy regulations when filtering by location or viewer identifiers
⚠️

Note: The viewer tags filter accepts both comma-separated strings and arrays. When using comma-separated values, ensure no spaces between tags (e.g., premium,verified not premium, verified).

Troubleshooting Common Filter Issues

No Results Returned

If your filtered query returns no results, check the following:

  1. Country Code Format: Ensure you're using uppercase 2-letter ISO codes

    • ✅ Correct: location.country=US
    • ❌ Incorrect: location.country=usa, location.country=United States, location.country=us

  2. Exact String Matching: Most filters use exact string matching

    • Device names are case-sensitive: iPad not ipad
    • Operating systems are case-sensitive: iOS not ios
    • City names must match exactly: New York not new york

  3. Date Range: Ensure your date range contains data

    • Maximum allowed range is 365 days
    • Dates must be in ISO 8601 format

  4. ObjectId Format: For contentId and appliedMediaProtectionSiemRule

    • Must be valid 24-character hex strings
    • Example: 68267a1db67be4c5088a008c

Filter Priority and Combination

  • All filters are combined with AND logic
  • More specific filters will narrow your results
  • Start broad and progressively add filters to identify where data drops off

Performance Tips

  • Use indexed fields for better performance:
    • contentId, project, createdAt are indexed
    • Location and device filters may be slower on large datasets
  • Limit date ranges for faster queries
  • Consider caching results for frequently used filter combinations

Migration from Legacy Endpoints

If you were previously using content-specific statistics endpoints, the new advanced filtering system provides more flexibility. Instead of querying statistics for individual content items, you can now:

  1. Filter project statistics by specific content ID using the contentId parameter
  2. Combine content filters with other dimensions for deeper insights
  3. Analyze multiple content items simultaneously using filters

For example, if you previously used a content-specific endpoint like:

GET /api/v1/contents/{contentId}/stats

You can now achieve the same result using:

GET /api/v1/projects/{projectId}/mediaprotection/stats/general?contentId={contentId}&startDate=...&endDate=...

The advanced filtering system provides a more powerful and flexible approach to analytics, eliminating the need for content-specific statistics endpoints in most use cases.

WatermarksTracking usage