The Engagement APIBeta reports how much of each moment of a piece of content viewers watched, aggregated across every completed view. It returns this data in two forms:

• A heatmap: an engagement value for every slice of the timeline, ordered from the start of the content to the end.
• Hotspots: a ranked list of the most or least engaging moments, each as a start time, an end time, and a score.

Engagement metrics are a subset of Mux Data's historical metrics. They're calculated from completed views, so they reflect how a whole population of viewers behaved rather than any single session.

Identify your content three ways

Every endpoint comes in three variants, one per identifier. All three return the same response shape, so pick the one that matches how you key your content.

The base path for all six endpoints is https://api.mux.com/data/v1/engagement.

Get a heatmap

A heatmap is an array of engagement values spread evenly across the content timeline, ordered from the start of the content to the end.

curl 'https://api.mux.com/data/v1/engagement/assets/{ASSET_ID}/heatmap?timeframe[]=7:days' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

{
  "total_row_count": 1,
  "timeframe": [1610025789, 1610112189],
  "data": {
    "total_views": 1024,
    "value": [0.42, 0.55, 0.61, 0.58, 0.47]
  }
}

API reference: AssetAPI, VideoAPI, Playback IDAPI.

The engagement values live in the data.value array:

• Each number is the engagement value for that slice of the timeline. The higher the value, the more viewers were watching that moment.
• The array runs from the start of the content to the end.
• The number of buckets is dynamic — somewhere between 10 and 1000 — and scales with the content's duration. Read the bucket count from the array length rather than hard-coding it.
• data.total_views is the number of views the heatmap was aggregated from.

Map buckets to timestamps

The buckets are evenly spaced, so once you know the content's duration you can turn any bucket index into a position in the content. Each bucket covers duration / value.length seconds:

// durationSeconds comes from your own metadata or the Mux asset
function bucketsToTimeline(value, durationSeconds) {
  const bucketSize = durationSeconds / value.length;
  return value.map((score, i) => ({
    startSeconds: i * bucketSize,
    endSeconds: (i + 1) * bucketSize,
    score,
  }));
}

Each engagement value is now paired with the time range it represents.

Get hotspots

Hotspots are the highest-scoring moments of the content, returned as discrete, ranked time ranges.

curl 'https://api.mux.com/data/v1/engagement/assets/{ASSET_ID}/hotspots?timeframe[]=7:days' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

{
  "total_row_count": 2,
  "timeframe": [1610025789, 1610112189],
  "data": {
    "total_views": 1024,
    "hotspots": [
      { "start_ms": 30000, "end_ms": 45000, "score": 0.842 },
      { "start_ms": 120000, "end_ms": 138000, "score": 0.713 }
    ]
  }
}

API reference: AssetAPI, VideoAPI, Playback IDAPI.

Each entry in data.hotspots describes one moment:

• start_ms — where the moment begins, in milliseconds from the start of the content.
• end_ms — where it ends, in milliseconds (exclusive).
• score — an engagement score between 0 and 1. Higher is more engaging.

By default, hotspots come back ordered from most to least engaging. data.total_views is the number of views they were aggregated from.

Query parameters

Hotspots take two optional query parameters:

To return the three least-engaging moments, sort ascending and set a limit:

curl 'https://api.mux.com/data/v1/engagement/videos/{VIDEO_ID}/hotspots?timeframe[]=30:days&order_direction=asc&limit=3' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

Scope with timeframe

Every endpoint accepts the standard Data timeframe[] query parameter to limit results to a window. Pass it as a relative duration or as a pair of epoch timestamps:

• Relative: timeframe[]=7:days or timeframe[]=24:hours
• Absolute range: timeframe[]=1610025789&timeframe[]=1610112189

If you leave it off, the timeframe defaults to the last 7 days. Engagement data follows the same retention as the rest of your Mux Data, so how far back you can query depends on your plan.

SDK version requirements

Engagement data is only collected by recent versions of the Mux Data SDKs. For a piece of content to have heatmaps and hotspots, the views must be reported by an integration on at least the version below. See the changelog announcement for details.