Getting Playback Position from XDR API

In this topic, you will learn the how to retrieve the viewer's playback position from the Cross-Device Resume (XDR) API.


Cross-device resume lets viewers start watching a video on one device, and at a later time, continue watching the video where they left off on a different device.

Because the Cross-Device Resume (XDR) API cannot be called from your client-side apps, you will need to create a server-side proxy to make the call and return the playback position value.

Getting playback position

You can get the viewer playback position with the Cross-Device Resume (XDR) API.

Cross-Device Resume (XDR) API

With the Cross-Device Resume API, you can get all the playhead positions for a specific viewer, or all the playheads for a specific viewer and video.

Base URL

The base URL for the API is:

Account path

In all cases, requests will be made for a specific Video Cloud Account. So, you will always add the term accounts followed by your account id to the base URL:


An access token for requests is required and must be present in the Authorization header:

Authorization: Bearer {access_token}

The access token is a temporary OAuth2 access token that must be obtained from the Brightcove OAuth service. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.


Requests to the Cross-Device Resume API must be made from client credentials with the following permissions:

  • video-cloud/xdr/read

Note that these permissions are not yet available in the Studio Admin UI. Until they are, you can use this Brightcove Learning Services app to create your client credentials. Just be sure to check the video-cloud/xdr/read box when you create the credentials (you can check as many other boxes as you like).

API methods

The Cross-Device Resume API supports the following requests. For details, see the Cross-Device Resume (XDR) API Reference.

Get viewer playheads

This request gets all of the playheads for a viewer.

GET /accounts/{accountID}/playheads/{viewer_id}
Response body

The response body contains an array of videos and playheads. It should look similar to this:

  "account_id": "1752604059001",
  "viewer_id": "viewer001",
  "items": [
    "timestamp": 1589548991563000,
    "video_id": "6152436480001",
    "playhead_seconds": 17
    "timestamp": 1589548858719000,
    "video_id": "6152440604001",
    "playhead_seconds": 3
  "size": 2

Get viewer video playheads

This request gets all of the playheads for a viewer and a specific video.

GET /accounts//playheads/{viewer_id}/

Response body

If you specify one video ID, the response body will contain one item object. When you specify more than one video ID, than the items array will contain multiple item objects. It should look similar to this:

  "account_id": "1752604059001",
  "viewer_id": "viewer001",
  "items": [
    "timestamp": 1589896539910000,
    "video_id": "6156696074001",
    "playhead_seconds": 39
  "size": 1

Using a server-side proxy

A proxy is a server-side application that acts as in intermediary between your client-side application and the REST API. Here are some helpful links: