Playback Analytics Deep Dive

Fastevo MP2 captures a rich telemetry stream for every protected asset. This playback analytics guide shows how to interact with the stats APIs, interpret responses, and translate raw numbers into product, growth, and security decisions.

The document is intentionally exhaustive: use it when you need to onboard a new analyst, design dashboards, or validate the semantics of the /stats API family.

1. API Quick Start

1.1 Base Path and Versioning

All endpoints share the prefix:

https://api.fastevo.net/api/v1/projects/mediaProtection/stats

Append the endpoint-specific suffix from the tables below.

1.2 Authentication

• Authorization: Bearer <PROJECT_API_KEY> for server-to-server workflows.
• Project-scoped user JWT for interactive dashboards.
• The token determines which project is queried; no explicit projectId parameter is accepted.
• Invalid or missing tokens return 401 Unauthorized.

1.3 Reporting Window

• startDate and endDate are mandatory ISO 8601 timestamps.
• Requests covering more than 365 days produce HTTP 400 and MEDIA_PROTECTION_QUERY_INVALID_PERIOD.
• Endpoints treat the window as inclusive and compare against UTC timestamps.

1.4 Pagination, Sorting, and Limits

• List endpoints accept page (default 1) and limit (default 20, maximum 100).
• Sorting parameters vary per endpoint; see the relevant section below.
• Responses echo pagination metadata (page, limit, total, pages) so you can build cursor logic.

1.5 Error Handling

• 400 responses indicate malformed filters, invalid dates, or unsupported values.
• 401 responses indicate authentication failures.
• 404 indicates the resource is not available to the authenticated project (rare for stats endpoints).
• 500 indicates an internal error; retry with exponential backoff, then contact support if the issue persists.

2. Filter Reference

Analytics endpoints share a common filter surface. Filters combine with AND logic; individual parameters that accept multiple values behave like OR clauses for that field.

2.1 Filter Inventory

2.2 Request Patterns

• Comma-separated OR: viewerTags=premium,VIP.
• Repeated parameter OR: viewerTags=premium&viewerTags=VIP.
• Boolean: use literal strings true or false.
• ObjectId: 24-character hex string. Invalid IDs are ignored (with a server warning log), so double-check values when the response looks empty.

2.3 Filter Combinations in Practice

2.4 Sample Filtered Request

curl -G \
  'https://api.fastevo.net/api/v1/projects/mediaProtection/stats/general' \
  -H 'Authorization: Bearer <PROJECT_API_KEY>' \
  --data-urlencode 'startDate=2025-01-01T00:00:00.000Z' \
  --data-urlencode 'endDate=2025-06-01T00:00:00.000Z' \
  --data-urlencode 'viewerTags=premium,early-access' \
  --data-urlencode 'location.country=US,CA' \
  --data-urlencode 'device=AppleTV,SmartTV' \
  --data-urlencode 'ipClassification=vpn,tor'

3. Metrics Dictionary

Use this section as a dictionary while inspecting responses.

3.1 Experience Metrics (General Stats)

Averages such as averagePlayTimeInSeconds appear only when the query returns at least one qualifying playback. Location or device facets may return null when metadata is unavailable for a session; handle those buckets explicitly in your dashboards.

3.2 Content Metrics

3.3 Viewer Metrics

3.4 Quality Metrics

3.5 Network Metrics

3.6 Security Metrics

4. Endpoint Catalog and Deep Dives

Each section below describes when to use the endpoint, the questions it answers, reference requests, sample responses, and interpretation tips.

4.1 Project Overview: /stats/general

Business questions

• What is the reach of my project over the selected window?
• Which countries, devices, and browsers dominate impressions?
• Are viewers actually playing content or abandoning early?

Sample request

curl -G \
  'https://api.fastevo.net/api/v1/projects/mediaProtection/stats/general' \
  -H 'Authorization: Bearer <PROJECT_API_KEY>' \
  --data-urlencode 'startDate=2025-01-01T00:00:00.000Z' \
  --data-urlencode 'endDate=2025-05-31T23:59:59.999Z' \
  --data-urlencode 'contentType=video' \
  --data-urlencode 'location.country=US,CA,GB'

Example response

{
  "totalImpressions": 15420,
  "totalPlaybacks": 12350,
  "totalPlayTimeInSeconds": 987650,
  "totalPauseTimeInSeconds": 45230,
  "averagePlayTimeInSeconds": 79.97,
  "averagePauseTimeInSeconds": 3.66,
  "averageCompletionPercent": 85.3,
  "impressionsPerCountry": [
    { "country": "US", "count": 8520 },
    { "country": "CA", "count": 3200 },
    { "country": "GB", "count": 2100 }
  ],
  "impressionsPerOsAndVersion": [
    { "osAndVersion": "iOS 17.5", "count": 4200 },
    { "osAndVersion": "Android 14", "count": 3800 }
  ],
  "impressionsPerOS": [
    { "os": "iOS", "count": 7800 },
    { "os": "Android", "count": 5620 },
    { "os": "Windows", "count": 1400 }
  ],
  "impressionsPerDevice": [
    { "device": "mobile", "count": 9800 },
    { "device": "desktop", "count": 4200 },
    { "device": "SmartTV", "count": 1420 }
  ],
  "impressionsPerBrowser": [
    { "browser": "Safari", "count": 6200 },
    { "browser": "Chrome", "count": 5800 },
    { "browser": "Edge", "count": 560 }
  ]
}

Interpretation tips

• Compare totalImpressions to totalPlaybacks to estimate drop-off before playback begins.
• Use impressionsPerCountry to prioritize localization or CDN expansion.
• A high averagePauseTimeInSeconds with modest averagePlayTimeInSeconds often signals buffering issues—triage with the quality endpoints.

4.2 Top Content: /stats/analytics/content/top

Business questions

• Which titles drive the most views or unique viewers?
• How efficiently do they engage audiences (completion, buffering, watch time)?

Sample request

curl -G \
  'https://api.fastevo.net/api/v1/projects/mediaProtection/stats/analytics/content/top' \
  -H 'Authorization: Bearer <PROJECT_API_KEY>' \
  --data-urlencode 'startDate=2025-01-01T00:00:00.000Z' \
  --data-urlencode 'endDate=2025-05-31T23:59:59.999Z' \
  --data-urlencode 'sortBy=uniqueViewers' \
  --data-urlencode 'limit=5'

Example response

{
  "data": [
    {
      "contentId": "68267a1db67be4c5088a008c",
      "title": "Launch Event Recap",
      "type": "video",
      "duration": 1865,
      "createdAt": "2025-01-15T12:03:22.000Z",
      "metrics": {
        "views": 1842,
        "uniqueViewers": 1620,
        "totalWatchTime": 132450,
        "avgWatchTime": 72,
        "avgCompletion": 82,
        "engagementScore": 87.4,
        "bufferingRatio": 1.4
      }
    }
  ],
  "pagination": { "page": 1, "limit": 5, "total": 42, "pages": 9 },
  "appliedFilters": {
    "sortBy": "uniqueViewers",
    "sortOrder": "desc",
    "limit": 5
  }
}

Interpretation tips

• Track uniqueViewers to understand reach vs. repeat consumption.
• engagementScore weights completion, play ratio, and low buffering—use it as a composite ranking when you need a single KPI.
• Combine with viewer filters (e.g. viewerTags=premium) to profile content resonance for specific cohorts.

4.3 Content Engagement: /stats/analytics/content/engagement

Business questions

• Which titles deliver sustained attention and low buffering?
• Where should editorial teams focus when improving session quality?

Sample response fragment

{
  "data": [
    {
      "contentId": "68267a1db67be4c5088a008d",
      "title": "Product Walkthrough",
      "engagementMetrics": {
        "avgEngagementScore": 78.5,
        "avgCompletionRate": 71,
        "avgPlayRatio": 0.89,
        "avgBufferingRatio": 0.02,
        "sessionCount": 940
      }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 18, "pages": 1 }
}

Interpretation tips

• avgPlayRatio close to 1 indicates viewers watch most of the asset; low values highlight potential pacing issues.
• Set minSessions to exclude long-tail content with insufficient samples.

4.4 Content Completion: /stats/analytics/content/completion

Business questions

• Which titles keep viewers through the end?
• Where does early drop-off occur, and how severe is it?

Sample response fragment

{
  "data": [
    {
      "contentId": "68267a1db67be4c5088a0099",
      "title": "Season Finale",
      "type": "video",
      "duration": 2640,
      "completionMetrics": {
        "avgCompletion": 91,
        "maxCompletion": 100,
        "minCompletion": 52,
        "completionRate": 88,
        "earlyDropoffRate": 7,
        "avgDropoffPoint": 63.4,
        "sessionCount": 1540
      }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 27, "pages": 2 }
}

Interpretation tips

• Watch the gap between avgCompletion and completionRate. High average with a low completion rate hints at bimodal behaviour (some viewers finish, others quit early).
• avgDropoffPoint (expressed as completion percent) shows where viewers bail, helping editors tighten pacing or insert calls-to-action.

4.5 Viewer Segments: /stats/analytics/viewer/segments

Business questions

• How are my identifiable viewers grouped by activity, watch time, completion, or variety?
• Who are the power viewers that need loyalty programs or pre-release access?

Segment definitions exposed by the API:

The API returns segment identifiers in snake_case (for example power_viewers). Map them to presentation labels in your client UI if you prefer title casing.

Example response fragment

{
  "summary": {
    "totalViewers": 8420,
    "totalSegments": 4,
    "segmentationMethod": "activity"
  },
  "segments": [
    {
      "segment": "power_viewers",
      "count": 1260,
      "percentage": 14.96,
      "metrics": {
        "avgSessions": 24.8,
        "avgWatchTimeMinutes": 410.5,
        "avgContentVariety": 6.4,
        "avgCompletion": 93
      },
      "topViewers": [
        {
          "viewerId": "customer-4412",
          "sessions": 26,
          "watchTime": 15420,
          "completion": 97,
          "contentVariety": 9,
          "lastSeen": "2025-05-28T18:42:11.000Z"
        }
      ]
    }
  ],
  "appliedFilters": { "segmentBy": "activity" }
}

Interpretation tips

• power_viewers are the power users referenced in product discussions—reward them with exclusive content and monitor them for early signals of churn.
• topViewers surfaces up to five sample profiles per segment, sorted by session count. watchTime is reported in seconds (raw playTime), while completion remains a percentage; convert units in your dashboard if you prefer minutes.
• Combine with viewerTags to compare subscribed vs. anonymous behaviour.

4.6 Viewer Retention: /stats/analytics/viewer/retention

Business questions

• Are viewers returning or churning after their first session?
• How does retention vary across cohorts (daily, weekly, monthly)?

Example response fragment

{
  "summary": {
    "totalViewers": 6120,
    "repeatViewers": 2840,
    "singleSessionViewers": 3280,
    "repeatViewersRate": 46.41,
    "singleSessionViewersRate": 53.59,
    "avgDaysActive": 6.2,
    "avgSessionsPerViewer": 3.4
  },
  "cohorts": [
    { "period": "2025-W18", "viewerCount": 820, "sessionCount": 2310 },
    { "period": "2025-W19", "viewerCount": 760, "sessionCount": 2140 }
  ],
  "appliedFilters": { "cohortGranularity": "week" }
}

Interpretation tips

• Pair retention cohorts with marketing campaigns to evaluate program impact.
• Track avgDaysActive to understand how long viewers stay engaged after their first touchpoint.

4.7 Viewer Activity Leaderboard: /stats/analytics/viewer/activity

Business questions

• Who are the top viewers by sessions, watch time, or completion?
• Which customers deserve proactive outreach from account teams?

Example response fragment

{
  "data": [
    {
      "viewerId": "enterprise-007",
      "activity": {
        "sessionCount": 34,
        "totalWatchTimeMinutes": 412,
        "avgWatchTimeMinutes": 12.1,
        "avgCompletion": 88,
        "contentVariety": 14,
        "firstSeen": "2025-02-04T11:02:44.000Z",
        "lastSeen": "2025-05-29T08:31:16.000Z",
        "daysActive": 115
      }
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 240, "pages": 12 }
}

Interpretation tips

• Use sortBy to align the leaderboard with business goals (e.g. longest watch time vs. highest completion).
• Combine with CRM data to personalize retention messaging.

4.8 Buffering Analytics: /stats/analytics/quality/buffering

Business questions

• Which days or devices suffer most from buffering?
• Are CDN or ISP issues localized to specific geographies?

Example response

{
  "summary": {
    "avgBufferingRatio": 2.8,
    "sessionsWithBuffering": 4120,
    "totalSessions": 9870
  },
  "timeSeries": [
    {
      "period": "2025-05-20",
      "avgBufferingRatio": 3.9,
      "maxBufferingRatio": 9.4,
      "minBufferingRatio": 0.3,
      "sessionCount": 540
    }
  ],
  "byDevice": [
    { "device": "SmartTV", "avgBufferingRatio": 5.6, "sessionCount": 920 },
    { "device": "AppleTV", "avgBufferingRatio": 4.1, "sessionCount": 610 }
  ]
}

Interpretation tips

• Spikes in maxBufferingRatio flag severe experiences even if the mean looks healthy.
• Use device drill-down to validate firmware or app release regressions.

4.9 Resolution Distribution: /stats/analytics/quality/resolution

Business questions

• What resolution do viewers actually experience?
• How much of the audience receives HD or UHD delivery?

Example response

{
  "distribution": [
    {
      "resolution": "4K UHD",
      "width": 3840,
      "height": 2160,
      "count": 820,
      "percentage": 8.6
    },
    {
      "resolution": "1080p",
      "width": 1920,
      "height": 1080,
      "count": 4620,
      "percentage": 48.2
    },
    {
      "resolution": "720p",
      "width": 1280,
      "height": 720,
      "count": 2830,
      "percentage": 29.5
    },
    {
      "resolution": "360p",
      "width": 640,
      "height": 360,
      "count": 620,
      "percentage": 6.5
    }
  ],
  "summary": {
    "mostCommon": "1080p",
    "highDefinitionPercentage": 56.8,
    "totalSessions": 9570
  }
}

Interpretation tips

• Track highDefinitionPercentage to ensure premium subscribers receive the quality they pay for.
• Combine with location filters to detect ISP-level throttling.

4.10 Hourly Patterns: /stats/analytics/time/hourly

Business questions

• When do viewers watch the most content?
• Which hours combine high volume with high engagement?

Example response

{
  "patterns": [
    {
      "time": { "hour": 20, "dayOfWeek": 5 },
      "sessions": 520,
      "uniqueViewers": 410,
      "metrics": {
        "avgWatchTimeMinutes": 9.4,
        "totalWatchTimeHours": 81.3,
        "avgCompletion": 86,
        "avgBufferingPercent": 1.8
      }
    }
  ],
  "heatmap": [
    [
      120, 90, 64, 22, 18, 12, 8, 10, 14, 36, 58, 72, 89, 112, 148, 196, 244,
      312, 360, 402, 520, 318, 198, 140
    ],
    [
      84, 52, 40, 18, 12, 6, 5, 8, 14, 24, 48, 56, 70, 88, 120, 168, 210, 248,
      284, 320, 356, 290, 180, 120
    ],
    [
      60, 42, 30, 16, 10, 6, 4, 6, 10, 20, 32, 48, 62, 74, 102, 140, 182, 210,
      238, 270, 300, 240, 150, 98
    ],
    [
      72, 50, 34, 20, 14, 8, 6, 8, 12, 22, 40, 58, 80, 94, 122, 160, 204, 236,
      268, 296, 320, 250, 160, 110
    ],
    [
      90, 62, 40, 22, 16, 10, 8, 10, 16, 28, 48, 68, 90, 112, 148, 186, 230,
      262, 296, 330, 360, 280, 170, 120
    ],
    [
      110, 76, 52, 26, 18, 12, 10, 12, 18, 32, 54, 76, 98, 126, 160, 198, 242,
      278, 312, 348, 380, 300, 188, 132
    ],
    [
      130, 88, 60, 28, 20, 14, 12, 14, 20, 36, 58, 82, 108, 138, 176, 214, 258,
      296, 330, 368, 400, 320, 200, 140
    ]
  ],
  "peaks": [
    { "time": { "hour": 20, "dayOfWeek": 5 }, "sessions": 520, "viewers": 410 }
  ],
  "summary": {
    "totalPeriods": 168,
    "avgSessionsPerPeriod": 238,
    "granularity": "hourly"
  },
  "appliedFilters": {}
}

The heatmap array lists seven rows (Sunday index 0 through Saturday index 6), with each row containing 24 hourly buckets.

Interpretation tips

• Use the heatmap to coordinate marketing pushes or live events around peak hours.
• dayOfWeek follows MongoDB numbering (1 = Sunday, 7 = Saturday); convert as needed for presentation.
• High avgBufferingPercent during specific hours may indicate regional ISP congestion; combine with country filters to confirm.

4.11 Bandwidth Metrics: /stats/analytics/network/bandwidth

Business questions

• What throughput do viewers experience, and how efficient is streaming vs. available bandwidth?
• Which devices or countries suffer from low throughput?

Example response

{
  "summary": {
    "totalSessions": 8640,
    "uniqueViewers": 5320,
    "avgEstimatedBandwidth": 8.4,
    "avgStreamBandwidth": 6.9,
    "totalBytesDownloaded": 48237619842,
    "bandwidthEfficiency": 82.1
  },
  "byDevice": [
    {
      "device": "AppleTV",
      "sessionCount": 1240,
      "avgBandwidth": 8.2,
      "avgEstimatedBandwidth": 10.4,
      "avgStreamBandwidth": 8.2,
      "totalBytesDownloaded": 9823412345,
      "bandwidthEfficiency": 78.8
    }
  ],
  "byLocation": [
    {
      "country": "US",
      "sessionCount": 4020,
      "avgBandwidth": 7.6,
      "avgEstimatedBandwidth": 9.1,
      "avgStreamBandwidth": 7.6,
      "totalBytesDownloaded": 21873451234,
      "bandwidthEfficiency": 83.5
    }
  ]
}

Interpretation tips

• bandwidthEfficiency under 60% indicates the player is not saturating the connection—investigate ABR ladders or throttling.
• Low avgEstimatedBandwidth in specific countries suggests regional ISP limitations; coordinate with CDN partners.

4.12 Security Threats: /stats/analytics/security/threats

Business questions

• How much of my traffic uses VPNs, proxies, or comes from risky IP ranges?
• Which countries concentrate suspicious activity?

Example response

{
  "summary": {
    "totalSessions": 6420,
    "vpnProxySessions": 820,
    "maliciousIpSessions": 140,
    "vpnProxyPercentage": 12.78,
    "maliciousIpPercentage": 2.18
  },
  "ipClassificationBreakdown": [
    { "classification": "vpn", "count": 620, "percentage": 9.65 },
    {
      "classification": "iCloudPrivateRelay",
      "count": 120,
      "percentage": 1.87
    },
    { "classification": "unclassified", "count": 4830, "percentage": 75.23 }
  ],
  "threatsByLocation": [
    {
      "country": "US",
      "threatCount": 320,
      "totalSessions": 3120,
      "threatPercentage": 10.26
    }
  ]
}

Interpretation tips

• Treat unclassified as neutral—the IP analyzer simply did not label the address.
• Monitor vpnProxyPercentage and maliciousIpPercentage alongside playback denial events to ensure access policies are working.

4.13 AI Analytics Report: /stats/analytics/ai-report

Business questions

• Need an executive-ready summary across all analytics without manual analysis?
• Want an AI-generated brief in a specific language for leadership updates?

Sample request

curl -G \
  'https://api.fastevo.net/api/v1/projects/mediaProtection/stats/analytics/ai-report' \
  -H 'Authorization: Bearer <PROJECT_API_KEY>' \
  --data-urlencode 'startDate=2025-04-01T00:00:00.000Z' \
  --data-urlencode 'endDate=2025-04-30T23:59:59.999Z' \
  --data-urlencode 'lang=en'

Example response

{
  "report": "# Executive Snapshot...",
  "metadata": {
    "startDate": "2025-04-01T00:00:00.000Z",
    "endDate": "2025-04-30T23:59:59.999Z",
    "language": "en",
    "appliedFilters": {}
  }
}

Interpretation tips

• The AI service runs the same analytics endpoints documented above (with fixed limits) and feeds the results into the AI prompt; ensure base data quality before sharing the report.
• Use lang for localized leadership summaries (e.g. lang=es).

5. Use Case Playbooks

5.1 Launch Readiness Review

1. Query /stats/general for the first 48 hours after launch.
2. Pull /analytics/content/top and /analytics/content/completion to confirm the flagship episodes are trending as expected.
3. Inspect /analytics/quality/buffering to ensure there are no device-specific regressions.
4. Share /analytics/ai-report with leadership as the daily digest.

5.2 Premium Subscriber Health

1. Filter every request with viewerTags=premium.
2. Use /analytics/viewer/segments to track how many premium viewers remain in the power_viewers and engaged_viewers cohorts.
3. Audit /analytics/viewer/retention to watch repeat viewer rates.
4. Combine /analytics/network/bandwidth and /analytics/quality/resolution to ensure premium subscribers receive HD/UHD streams.

5.3 Fraud and Abuse Monitoring

1. Call /analytics/security/threats daily with ipClassification=vpn,tor filters.
2. Cross-reference suspicious countries with /analytics/network/bandwidth to see if they consume disproportionate bandwidth.
3. For high-risk viewers, use /analytics/viewer/activity to enumerate the accounts and trigger additional verification in your back office.

5.4 Device Release QA

1. During rollout of a new app version, filter requests with clientVersion=<new_version>.
2. Compare /analytics/quality/buffering and /analytics/content/engagement metrics to the previous version to evaluate regressions.
3. Track /analytics/viewer/segments for that version to ensure engagement remains within tolerance.

6. Best Practices and Troubleshooting

6.1 Operational Tips

• Start broad: run queries without filters to confirm data availability, then layer filters incrementally.
• Cache dashboards: heavy aggregation pipelines can take longer on large datasets. Cache results when refreshing more frequently than every few minutes.
• Coordinate with data warehouse: export analytics responses to your BI tool for historical comparisons—every endpoint returns JSON that can be flattened.

6.2 Troubleshooting Checklist

6.3 Data Hygiene Recommendations

• Persist viewerIdentifier consistently so viewers can be segmented; anonymous sessions will be excluded from viewer analytics.
• Keep device strings normalized (e.g. AppleTV instead of apple tv) to avoid fragmented device reporting.
• Maintain accurate viewer tags (premium, trial, beta) to unlock richer cohort analysis.

Armed with this guide, you can design dashboards, debug anomalies, or brief executives without spelunking through backend code. Combine the filter recipes, metric definitions, and endpoint walkthroughs above to craft analytics pipelines that match your business goals.