support Contact Support | system status System Status
Page Contents

    Analytics API: Live Metrics

    This topic explains the analytics metrics available for Live streams.

    Introduction

    Playback metrics for Live streams served by the Brightcove Live service are available in realtime, through the Analtyics API. This data is captured for live streams only; VOD playback is not included.

    The API provides Live stream metrics via 2 endpoints:

    • /v1/timeseries
    • /v1/events

    Both query the same data set, but aggregate the results differently. This document describes the usage and syntax of each.

    Metrics

    These are the metrics available via the Live endpoints. Queries may request multiple metrics.

    Metric Description
    alive_ss_ad_start Server-side ad impressions
    ccu Unique sessions; count of distinct (fingerprint + Session)
    fingerprint_count Unique devices; count of distinct fingerprints (see below)
    video_impression Number of times video was loaded into player
    video_seconds_viewed Total seconds watched by all viewers
    video_view Stream starts (not unique)

    For unique tracking, we assign a fingerprint to each device by combining (Remote IP + User-Agent + Player). Note that we don’t use an actual hardware ID from the device itself - this reduces accuracy, but keeps us privacy-compliant.

    Dimensions

    The following combinations are supported as dimensions and where filter keys:

    • video
    • video, country
    • video, device_type

    Query Parameters

    Both Live endpoints share some common parameters that control the scope and grouping of the query.

    Parameter Syntax Required Default Description
    dimensions <dim1>,<dim2>,... Y - Query dimensions (GROUP BY)
    metrics <metric1>,<metric2>,... Y - One or more metrics to report
    where <dim1>=<value1>;... Y - One or more query filters; must include at least 1 video
    from <epoch> N 0 Time range begin
    to <epoch> N now Time range end

    Time Series

    The /v1/timeseries endpoint returns a list of points along a timeline, with the value of the requested metric at each point in time. Points are 1 minute buckets by default, but can be changed via a parameter.

    In this context, Unique metrics (ccu, fingerprint_count) indicate the maximum value at any time during each bucket. So a query with bucket_duration=1d will return the maximum concurrency for each day, while a query with bucket_limit=1 will return the maximum concurrency at any point in the stream.

    URI

    /v1/timeseries/accounts/$account

    Additional Parameters

    Parameter Syntax Required Default Description
    bucket_duration <n>m (minutes)
    <n>h (hours)
    <n>d (days)
    N 1m Duration represented by each point. 1d is 24 hours, not a Calendar day.
    bucket_limit <n> N - Number of points to return. Use either bucket_duration or bucket_limit, but not both together.

    Response

    {
    "<metric1>": {
    "data": [
      {
        "dimensions": {
            "account": "<account>",
            "<dim1>": "<key1>",
            ...
            "<dimN>": "<keyN>"
          },
        "points": [
          {
            "timestamp": <bucket1>,
            "value": <value1>
          },
          ...,
          {
            "timestamp": <bucketN>,
            "value": <valueN>
          },
        ]
      }
    ]
    },
    "<metric2>": {
    ...
    },
    ...
    }
    

    Events

    The /v1/events endpoint returns metric totals for all or part of a Live video stream.

    In this context, Unique metrics (ccu, fingerprint_count) represent the total value over the query range. So for example, a query without from/to parameters will return the total number of unique sessions (ccu) and/or devices (fingerprint_count) for the entire stream.

    URI

    /v1/events/accounts/$account

    Additional Parameters

    none

    Response

    {
    "data": [
    {
      "dimensions": {
        "account": "<account>",
        "<dim1>": "<key1>",
        ...
        "<dimN>": "<keyN>"
      },
      "totals": {
        "<metric1>": <value1>,
        ...
        "<metricN>": <valueN>
      }
    }
    ]
    }
    

    Export

    The Events endpoint also provides a downloadable report:

    /v1/events/accounts/$account/videos/$video/export?format=xlsx

    The response is an XLSX file with Live metrics on 4 Sheets:

    • Summary
    • Concurrent users
    • Views by Device Type
    • Views by Geography

    Usage Examples

    For all these examples, we’ll use Account 1234, Video 5555, and assume a current time of 12:00:00 PM UTC on Feb 15th, 2020.


    Get the current Viewer count (CCU) for a Live Stream or Channel

    Set from to at least 2 minutes ago (11:58 AM), and use the last point in the response.

    /v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581767880000


    Get CCU graph points for a Live stream over the past 24 hours

    Zoom in (1-minute points)

    /v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581681600000&bucket_duration=1m

    Zoom out (1-hour points)

    /v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581681600000&bucket_duration=1h


    Get the maximum CCU per day for a Live channel over the past 7 days

    /v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&from=1581206400000&bucket_duration=1d


    Get the maximum CCU at any time during a Live stream

    /v1/timeseries/accounts/1234?dimensions=video&metrics=ccu&where=video==5555&bucket_limit=1


    Get the total Unique Viewers and Seconds Viewed for multiple Live streams

    Video 5555 has completed; numbers are final. Video 5556 is still active; numbers are running totals.

    /v1/events/accounts/1234?dimensions=video&metrics=fingerprint_count,video_seconds_viewed&where=video==5555,5556


    Get the Viewership and Ad totals for an hour-long program on a Live channel<

    Program aired from 10:00 AM until 11:00 AM (UTC)

    /v1/events/accounts/1234?dimensions=video&metrics=alive_ss_ad_start,video_view,fingerprint_count&where=video==5555&from=1581760800000&to=1581764399999


    Get Viewership by Country for the duration of a Live stream

    /v1/events/accounts/1234?dimensions=video,country&metrics=video_view,fingerprint_count&where=video==5555


    Page last updated on 12 Jun 2020