---
title: "Get Engagement Heatmap for a Playback ID"
method: GET
path: "/data/v1/engagement/playback-ids/{PLAYBACK_ID}/heatmap"
tags: ["Engagement"]
---

# Get Engagement Heatmap for a Playback ID

`GET /data/v1/engagement/playback-ids/{PLAYBACK_ID}/heatmap`

## Request

- Base URL: `https://api.mux.com`
- URL: `https://api.mux.com/data/v1/engagement/playback-ids/{PLAYBACK_ID}/heatmap`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Returns the engagement heatmap for a playback ID. The heatmap is an array of per-bucket engagement values across the content timeline, where the number of buckets scales with the content duration. Each value represents how engaged viewers were with that portion of the content. This only covers views for this specific playback ID; to analyze the entire asset across all of its playback IDs, use the asset ID or video ID endpoint instead.

## Path parameters

- `PLAYBACK_ID` string, required

## Query parameters

- `timeframe` string[]

## Response `200`

OK

- GetEngagementHeatmapResponse
  - `data` EngagementHeatmap, required
    - `heatmap` number[], required: Per-bucket engagement values across the content timeline, ordered from the start to the end of the content. The number of buckets is dynamic (between 10 and 1000) and scales with the content duration.
    - `asset_id` string, nullable: The asset ID for which the heatmap was calculated. Omitted if the heatmap is associated with a video_id or playback_id.
    - `playback_id` string, nullable: The playback ID for which the heatmap was calculated. Omitted if the heatmap is associated with a video_id or asset_id.
    - `video_id` string, nullable: The video ID for which the heatmap was calculated. Omitted if the heatmap is associated with a playback_id or asset_id.
  - `total_row_count` integer, nullable, required
  - `timeframe` integer[], required

## Changes

- **2026-09-30** `99c1d509dcbb`: 1 warning, 1 info
  - deleted the `query` request parameter `timeframe[]`
  - added the new optional `query` request parameter `timeframe`
- **2026-09-30** `4fb3ee354107`: 2 breaking, 4 info
  - removed the required property `data/total_views` from the response with the `200` status
  - removed the required property `data/value` from the response with the `200` status
  - added the optional property `data/asset_id` to the response with the `200` status
  - added the optional property `data/playback_id` to the response with the `200` status
  - …2 more
- **2026-08-12** `5b4b3133f27d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/muxinc/apis/mux-api/changes/data/v1/engagement/playback-ids/:PLAYBACK_ID/heatmap/get.md)

---

[API](https://skmtc.dev/muxinc/apis/mux-api.md) - [All operations](https://skmtc.dev/muxinc/apis/mux-api/llms.txt) - [OpenAPI document](https://skmtc.dev/muxinc/apis/mux-api/revisions/75b4251a1d96?raw)