Skip to Content
Mux Docs: Home

Show how many people are watching your videos

Learn how to get the latest view and unique viewer counts for a video using the Engagement Counts API.

In this guide you will learn how to use the Engagement CountsBeta API in order to embed the latest view and unique viewer counts for a particular video ID into your applications.

You will use JSON Web Tokens to authenticate to this API.

1Create a Signing Key

Signing keys can be managed (created, deleted, listed) from the Signing Keys settings of the Mux dashboard or via the Mux System API.

When making a request to the System API to generate a signing key, the access token being used must have the System permission. You can confirm whether your access token has this permission by going to Settings > API Access Token. If your token doesn't have the System permission listed, you'll need to generate another access token with all of the permissions you need, including the System permission.

When creating a new signing key, the API will generate a 2048-bit RSA key pair and return the private key and a generated key ID; the public key will be stored at Mux to validate signed tokens. Store the private key in a secure manner.

You probably only need one signing key active at a time and can use the same signing key when requesting counts for multiple videos. However, you can create multiple signing keys to enable key rotation, creating a new key and deleting the old only after any existing signed URLs have expired.

Request:

curl -X POST \
-H "Content-Type: application/json" \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET} \
'https://api.mux.com/system/v1/signing-keys'

Response

// POST https://api.mux.com/system/v1/signing-keys
{
"data": {
"private_key": "(base64-encoded PEM file with private key)",
"id": "(unique signing-key identifier)",
"created_at": "(UNIX Epoch seconds)"
}
}

Be sure that the signing key's environment (Staging, Production, etc.) matches the environment of the views you would like to count! When creating a signing key via API, the environment of the access token used for authentication will be used.

This can also be done manually via the UI. If you choose to create and download your signing key as a PEM file from UI, you will need to base64 encode it before using it with (most) libraries.

cat /path/to/file/my_signing_key.pem | base64
LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktL...

2Generate a JSON Web Token

The following JWT claims are required:

Claim CodeDescriptionValue
subSubject of the JWTThe ID for which counts will be returned
audAudience (identifier type)video_id (Mux Data Video ID)
asset_id (Mux Video Asset ID)
playback_id (Mux Video Playback ID)
live_stream_id (Mux Video Live Stream ID)
expExpiration timeUNIX Epoch seconds when the token expires. Use this to ensure any tokens that are distributed become invalid after a period of time.
kidKey IdentifierKey ID returned when signing key was created

Each of these ID types (used for the aud claim) are distinct and cannot be used interchangeably. Video ID is an optional Data dimension provided by the customer (you!). For more information on leveraging Video ID, see how to Make your data actionable. Mux Video Asset ID, Playback ID and Live Stream ID are available to Mux Video customers only and are generated by Mux. Be sure to double check both the query ID type and value!

Expiration time

Expiration time should be at least the duration of the video or the expected duration of the live stream. When the signed URL expires, you will no longer receive counts from the API.

Your application should consider cases where the user loads a video, leaves your application, then comes back later at some time in the future and tries to play the video again. You will likely want to detect this behavior and make sure you fetch a new signed URL to make sure the counts that are displayed in your application continue to display.

3Signing the JWT

The steps can be summarized as:

  1. Load the private key used for signing
  2. Assemble the claims (sub, aud, exp, kid etc) in a map
  3. Encode and sign the JWT using the claims map and private key and the RS256 algorithm.

There are dozens of software libraries for creating and reading JWTs. Whether you’re writing in Go, Elixir, Ruby, or a dozen other languages, don’t fret, there’s probably a JWT library that you can rely on. For a list of open source libraries to use, check out jwt.io.

The following examples assume you're working with either a private key returned from the API, or copy & pasted from the Dashboard, not when downloaded as a PEM file. If you've downloaded it as a PEM file, you will need to base64 encode the file contents.

package main
import (
"encoding/base64"
"fmt"
"log"
"time"
"github.com/golang-jwt/jwt/v4"
)
func main() {
myId := "" // Enter the id for which you would like to get counts here
myIdType := "" // Enter the type of ID provided in my_id; one of video_id | asset_id | playback_id | live_stream_id
keyId := "" // Enter your signing key id here
key := "" // Enter your base64 encoded private key here
decodedKey, err := base64.StdEncoding.DecodeString(key)
if err != nil {
log.Fatalf("Could not base64 decode private key: %v", err)
}
signKey, err := jwt.ParseRSAPrivateKeyFromPEM(decodedKey)
if err != nil {
log.Fatalf("Could not parse RSA private key: %v", err)
}
token := jwt.NewWithClaims(jwt.SigningMethodRS256, jwt.MapClaims{
"sub": myId,
"aud": myIdType,
"exp": time.Now().Add(time.Minute * 15).Unix(),
"kid": keyId,
})
tokenString, err := token.SignedString(signKey)
if err != nil {
log.Fatalf("Could not generate token: %v", err)
}
fmt.Println(tokenString)
}

4Making a Request

Supply the JWT in the resource URL using the token query parameter. The API will inspect and validate the JWT to make sure the request is allowed.

Example:

curl 'https://stats.mux.com/counts?token={JWT}'

Response:

{
"data": [{ "views": 95, "viewers": 94, "updated_at": "2021-09-28T18:21:19Z" }]
}
  • views is the total (non-unique) number of views happening
  • viewers is the total unique number of views happening

Uniqueness is determined by the viewer_user_id metadata field. See the Metadata guide for details on adding metadata fields.

Was this page helpful?