---
title: "Record Media Played Percentage"
method: POST
path: "/media-bridge/2026-09/events/media-played-percent"
tags: ["Advanced"]
---

# Record Media Played Percentage

`POST /media-bridge/2026-09/events/media-played-percent`

## Request

- Base URL: `https://api.hubapi.com`
- URL: `https://api.hubapi.com/media-bridge/2026-09/events/media-played-percent`
- Auth: OAuth 2
  - Authorization code: `https://app.hubspot.com/oauth/authorize`
  - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `media_bridge.write`

This endpoint allows you to record the percentage of media that has been played. It is useful for tracking user engagement with media content, such as videos or audio files, by capturing the extent to which the media has been consumed. This data can be used for analytics and improving content delivery strategies.

## Request body

- MediaPlayedPercentageEventRequest
  - `_hsenc` string: HubSpot encoding parameter for tracking purposes.
  - `contactId` integer: The unique identifier for the contact associated with the media play event.
  - `contactUtk` string: The user token key associated with the contact.
  - `externalId` string: An external identifier for the media, provided by the user.
  - `externalPlayContext` 'EMAIL' | 'EXTERNAL_PAGE': Additional context provided externally about the media play event.
  - `mediaBridgeId` integer: The unique identifier for the media bridge instance.
  - `mediaName` string: The name of the media that was played.
  - `mediaType` 'AUDIO' | 'DOCUMENT' | 'IMAGE' | 'OTHER' | 'VIDEO', required: The type of media that was played. Valid values include 'VIDEO', 'AUDIO', 'DOCUMENT', 'OTHER', and 'IMAGE'.
  - `mediaUrl` string: The URL where the media is hosted.
  - `occurredTimestamp` integer, required: The timestamp when the media play event occurred.
  - `pageId` integer: The unique identifier for the page where the media was played.
  - `pageName` string: The name of the page where the media was played.
  - `pageUrl` string: The URL of the page where the media was played.
  - `playedPercent` integer, required: The percentage of the media that has been played.
  - `sessionId` string, required: The unique identifier for the session in which the media was played.

## Response `200`

successful operation

- MediaPlayedPercentageEvent
  - `contactId` integer, required: The unique identifier for the contact associated with the media event. It is a string value.
  - `externalPlayContext` 'EMAIL' | 'EXTERNAL_PAGE': Contextual information about the external environment where the media is played. It is a string value.
  - `mediaBridgeId` integer, required: The unique identifier for the media bridge instance. It is a string value.
  - `mediaBridgeObjectCoordinates` string, required: Coordinates that specify the location of the media bridge object. It is a string value.
  - `mediaBridgeObjectTypeId` string, required: The type identifier for the media bridge object. It is a string value.
  - `mediaName` string, required: The name of the media content being played. It is a string value.
  - `mediaType` 'AUDIO' | 'DOCUMENT' | 'IMAGE' | 'OTHER' | 'VIDEO', required: The type of media being played, such as 'VIDEO', 'AUDIO', etc. It is a string value.
  - `mediaUrl` string: The URL of the media content being played. It is a string value.
  - `occurredTimestamp` integer, required: The timestamp when the media play event occurred. It is a string value in ISO 8601 format.
  - `pageId` integer: The unique identifier for the page where the media is being played. It is a string value.
  - `pageName` string: The name of the page where the media is being played. It is a string value.
  - `pageObjectCoordinates` string: Coordinates that specify the location of the page object. It is a string value.
  - `pageUrl` string: The URL of the page where the media is being played. It is a string value.
  - `playedPercent` integer, required: The percentage of the media content that has been played. It is a number value.
  - `portalId` integer, required: The unique identifier for the HubSpot portal. It is an integer value.
  - `providerId` integer, required: The unique identifier for the media provider. It is a string value.
  - `sessionId` string, required: The unique identifier for the session during which the media was played. It is a string value.

## Other responses

- `default`: An error occurred.

---

[API](https://skmtc.dev/hubspot/apis/cms-media-bridge.md) - [All operations](https://skmtc.dev/hubspot/apis/cms-media-bridge/llms.txt) - [OpenAPI document](https://skmtc.dev/hubspot/apis/cms-media-bridge/revisions/8f11766b98c4?raw)