--- title: "Get Video heatmap data" method: GET path: "/library/{libraryId}/videos/{videoId}/play/heatmap" tags: ["Manage Videos"] --- # Get Video heatmap data `GET /library/{libraryId}/videos/{videoId}/play/heatmap` ## Request - Base URL: `https://video.bunnycdn.com` - URL: `https://video.bunnycdn.com/library/{libraryId}/videos/{videoId}/play/heatmap` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns raw heatmap data for the video, used to render the attention heatmap on the player timeline. Returns an empty string if the library has heatmaps disabled or no heatmap data exists yet. ## Path parameters - `libraryId` integer, required - `videoId` string, required ## Query parameters - `token` string, nullable - `expires` integer ## Response `200` The heatmap data of the requested video - VideoPlayDataModel - `video` VideoModel - `videoLibraryId` integer, required: The ID of the video library that the video belongs to - `guid` string, required: The unique ID of the video - `title` string, required: The title of the video - `description` string, nullable: The description of the video - `dateUploaded` string, date-time, required: The date when the video was uploaded - `views` integer, required: The number of views the video received - `isPublic` boolean, required: Determines if the video is publically accessible - `length` integer, required: The duration of the video in seconds - `status` union, required - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - `framerate` number, double, required: The framerate of the video - `rotation` integer, nullable: Rotation of the source file in degrees as read from container metadata (e.g. 90, -90, 180, 270); null when no rotation metadata is present. - `width` integer, required: The width of the original video file - `height` integer, required: The height of the original video file - `availableResolutions` string, nullable: Comma-separated list of resolution labels (e.g. "360p,720p,1080p") that have finished encoding and are available for playback. - `outputCodecs` string, required: Comma-separated list of output codecs generated for this video (e.g. "x264,vp9"). See EncoderOutputCodec for possible values. - `thumbnailCount` integer, required: The number of thumbnails generated for this video - `encodeProgress` integer, required: Encoding progress as a percentage from 0 to 100; reaches 100 when transcoding finishes. - `storageSize` integer, required: Total storage used by this video, in bytes. - `captions` CaptionModel[], nullable: The list of captions available for the video - `srclang` string, nullable: The unique srclang shortcode for the caption - `label` string, nullable: The text description label for the caption - `version` integer: Increments each time this caption is replaced; useful as a cache-busting value for the caption file URL. - `hasMP4Fallback` boolean, required: Determines if the video has MP4 fallback files generated - `collectionId` string, nullable: The ID of the collection where the video belongs - `thumbnailFileName` string, nullable: The file name of the thumbnail inside of the storage - `thumbnailUrl` string, nullable: The CDN URL of the thumbnail - `thumbnailBlurhash` string, nullable: Thumbnail blurhash to show while the actual thumbnail is being loaded - `averageWatchTime` integer, required: The average watch time of the video in seconds - `totalWatchTime` integer, required: The total video watch time in seconds - `category` string, nullable: Automatically detected content category label; "untagged" when no category has been determined yet. - `chapters` ChapterModel[], nullable: The list of chapters available for the video - `title` string, required: The title of the chapter, up to 255 characters. - `start` integer: The start time of the chapter in seconds. Must be less than End and within the video's duration; chapters must not overlap each other. - `end` integer: The end time of the chapter in seconds. Must be greater than Start and within the video's duration; chapters must not overlap each other. - `moments` MomentModel[], nullable: The list of moments available for the video - `label` string, required: The text description label for the moment, up to 255 characters. - `timestamp` integer: The timestamp of the moment in seconds. Must be within the video's duration. - `metaTags` MetaTagModel[], nullable: The list of meta tags that have been added to the video - `property` string, nullable: The meta tag key. Must match ^[A-Za-z0-9._:'"-]+$. Setting a tag with the property "description" also updates the video's Description field. - `value` string, nullable: The meta tag value. HTML/markup is stripped and the value is stored as plain text. - `transcodingMessages` TranscodingMessageModel[], nullable: The list of transcoding messages that describe potential issues while the video was transcoding - `timeStamp` string, date-time: Date and time when this message was added (UTC). - `level` union - 0: Shouldn't be used - 1: An info message to the user, shouldn't break anythying - 2: A warning message, for example that the transcoded video may break when playing - 3: An error, meaning that the video will most likely not be playable - `issueCode` union - 0: Shouldn't be used - 1: Marks that there is a mismatch between lengths of audio and video streams in the transcoded file - 2: Marks that transcoding completed with warnings - 3: Marks that original video file has incompatible resolution or isn't a video stream - 4: Marks that original video file has invalid framerate - 5: Marks that video stream exceeded max duration - 6: Marks that audio stream exceeded max duration - 7: Marks that video file is corrupted and couldn't be processed properly - 8: Marks that video transcription finished with errors and might not be complete - 9: Marks that video file is not compatible with JIT encoding - 10: Marks that video failed JIT encoding - 11: Marks that captions generation failed - 12: Marks that the uploaded or fetched file is not video or audio, for example a photo or a document - `message` string, nullable: Human-readable description of the issue. - `value` string, nullable: Additional context value for the issue, if applicable; otherwise empty. - `jitEncodingEnabled` boolean, nullable: Whether just-in-time encoding is enabled for this specific video, overriding the video library's default JitEncodingEnabled setting when set. Null means the library default applies. - `smartGenerateStatus` union - 0 - 1 - 2 - 3 - 4 - `smartGenerateFeaturesStatus` SmartGenerateFeaturesStatusModel - `title` union - 0 - 1 - 2 - 3 - 4 - `description` union - 0 - 1 - 2 - 3 - 4 - `chapters` union - 0 - 1 - 2 - 3 - 4 - `moments` union - 0 - 1 - 2 - 3 - 4 - `hasOriginal` boolean, nullable: Determines if video has the original file available in storage - `originalHash` string, nullable: Original uploaded file SHA256 hash - `hasHighQualityPreview` boolean, nullable: Whether a high-quality animated preview has been generated for this video. - `libraryName` string, nullable: The name of the video library. - `pullZoneId` integer: The pull zone ID backing the video library's CDN delivery. - `captionsPath` string, nullable: CDN URL of the directory containing the video's caption (.vtt) files. - `seekPath` string, nullable: CDN URL of the directory containing the video's seek/scrub thumbnail sprites. - `thumbnailUrl` string, nullable: CDN URL of the video's thumbnail image. - `fallbackUrl` string, nullable: CDN URL prefix for the video's MP4 fallback renditions. - `videoPlaylistUrl` string, nullable: CDN URL of the video's HLS master playlist. - `originalUrl` string, nullable: CDN URL of the original uploaded source file. Only populated when the library allows early/original playback. - `previewUrl` string, nullable: CDN URL of the video's animated preview (scrub thumbnail). - `controls` string, nullable: Comma-separated list of player control identifiers enabled for this library. - `enableDRM` boolean: Whether DRM protection is enabled for this video. - `drmVersion` integer: DRM protection tier applied to this video, as an integer cast of the Basic/Enterprise tier enum. Only relevant when EnableDRM is true. - `playerKeyColor` string, nullable: The player's accent/key color, as a CSS color value. - `vastTagUrl` string, nullable: VAST ad tag URL used to serve ads in the player; empty when ads are disabled. - `viAiPublisherId` string, nullable: Publisher ID for the vi.ai advertising integration; ads are enabled in the player when this is non-empty. - `captionsFontSize` integer: Caption font size in pixels. - `captionsFontColor` string, nullable: CSS color value for the caption text. - `captionsBackground` string, nullable: CSS color value for the caption background. - `uiLanguage` string, nullable: Locale code for the player's UI language (e.g. "en"). - `allowEarlyPlay` boolean: Whether the video can be played from the original source file before encoding has finished. - `tokenAuthEnabled` boolean: Whether the library's CDN delivery requires signed URLs for playback assets (segments, manifests, thumbnails, etc.). This is a separate setting from whether this endpoint itself required a token to return data. - `enableMP4Fallback` boolean: Whether MP4 fallback renditions are available for players that cannot use HLS. - `showHeatmap` boolean: Whether the attention heatmap is enabled for this library's player. - `fontFamily` string, nullable: CSS font-family value used by the player. - `playbackSpeeds` string, nullable: Comma-separated list of playback speed multipliers offered to the viewer (e.g. "0.5,1,1.5,2"). - `widevineMinClientSecurityLevel` integer, nullable: Minimum required Widevine client security level (1-3). Ignored (always null here) when WidevineSdOnlyForL3 is enabled, since that setting takes precedence. - `widevineEmeRobustness` string, nullable: EME robustness string corresponding to WidevineMinClientSecurityLevel (e.g. "SW_SECURE_CRYPTO", "HW_SECURE_DECODE"); null when no minimum level applies. - `widevineSdOnlyForL3` boolean: When true, Widevine L3 (software-only) clients are capped to SD playback while stronger clients play at full quality; overrides WidevineMinClientSecurityLevel when both are set. - `maxSoftwareWidevineResolution` integer, nullable: Maximum vertical resolution allowed for software (L3) Widevine clients when WidevineSdOnlyForL3 is enabled; null otherwise. - `zoneTier` integer, nullable: Pull zone tier associated with this video library (integer enum value). - `isPlayable` boolean: Determines if the video is currently playable using either playlist or original source. - `isPlaylistPlayable` boolean: Determines if the HLS playlist is currently playable. - `preferredPlaybackSource` union - 'None' - 'Playlist' - 'Original' - `rememberPlayerPosition` boolean: Whether the player resumes from the viewer's last watched position. - `customCss` string, nullable: Custom CSS injected into the player. Only populated when the caller explicitly requests it. - `exposeVideoMetadata` boolean: Whether JSON-LD structured data (schema.org VideoObject markup) is rendered for this video, e.g. for SEO. - `enableCompactControls` boolean: Whether the player uses a compact control bar layout. ## Other responses - `401`: The request authentication failed - `404`: The requested video was not found - `500`: Internal Server Error ## Changes - **2026-11-12** `83116184952f`: 7 breaking, 41 info - added `#/components/schemas/IssueCodes` to the `video/oneOf[#/components/schemas/VideoModel]/transcodingMessages/items/issueCode` response property `oneOf` list for the response status `200` - added `#/components/schemas/Severity` to the `video/oneOf[#/components/schemas/VideoModel]/transcodingMessages/items/level` response property `oneOf` list for the response status `200` - added `subschema #1: Created, subschema #2: Uploaded, subschema #3: Processing, subschema #4: Transcoding, subschema #5: Finished, subschema #6: Error, subschema #7: UploadFailed, subschema #8: JitSegmenting, subschema #9: JitPlaylistsCreated` to the `video/oneOf[#/components/schemas/VideoModel]/status/oneOf[#/components/schemas/VideoModelStatus]/` response property `oneOf` list for the response status `200` - added `subschema #1: None, subschema #2: Playlist, subschema #3: Original` to the `preferredPlaybackSource/oneOf[#/components/schemas/VideoPlaybackSource]/` response property `oneOf` list for the response status `200` - …44 more [Operation history](https://skmtc.dev/bunny/apis/stream-api/changes/library/:libraryId/videos/:videoId/play/heatmap/get.md) --- [API](https://skmtc.dev/bunny/apis/stream-api.md) - [All operations](https://skmtc.dev/bunny/apis/stream-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bunny/apis/stream-api/revisions/83116184952f?raw)