LIlivepeer
metrics

Query viewership metrics

Changed on

Requires a private (non-CORS) API key to be used.

get/data/views/query

Request

  • Base URL
    https://livepeer.studio/api
  • URL
    https://livepeer.studio/api/data/views/query
  • Auth
    HTTP bearer

Query parameters

playbackIdstring

The playback ID to filter the query results. This can be a canonical playback ID from Livepeer assets or streams, or dStorage identifiers for assets

string date-time
OR
integer

Start timestamp for the query range (inclusive)

string date-time
OR
integer

End timestamp for the query range (exclusive)

timeStep'hour' | 'day' | 'week' | 'month' | 'year'

The time step to aggregate viewership metrics by

assetIdstring

The asset ID to filter metrics for

streamIdstring

The stream ID to filter metrics for

creatorIdstring

The creator ID to filter the query results

breakdownBy[]string[]

The list of fields to break down the query results. Specify this query-string multiple times to break down by multiple fields.

Response

A list of Metric objects

playbackIdstring

The playback ID associated with the metric.

creatorIdstring

The ID of the creator associated with the metric.

viewerIdstring

The ID of the viewer associated with the metric.

dStorageUrlstring

The URL of the distributed storage used for the asset

timestampnumber

Timestamp (in milliseconds) when the metric was recorded. If the query contains a time step, this timestamp will point to the beginning of the time step period.

devicestring

The device used by the viewer.

deviceTypestring

The type of the device used by the viewer.

cpustring

The CPU used by the viewer's device.

osstring

The operating system used by the viewer.

browserstring

The browser used by the viewer.

browserEnginestring

The browser engine used by the viewer's browser.

continentstring

The continent where the viewer is located.

countrystring

The country where the viewer is located.

subdivisionstring

The subdivision (e.g., state or province) where the viewer is located.

timezonestring

The timezone where the viewer is located.

geohashstring

Geographic encoding of the viewers location. Accurate to 3 digits.

viewCountinteger required

The number of views for the stream/asset.

playtimeMinsnumber required

The total playtime in minutes for the stream/asset.

ttffMsnumber

The time-to-first-frame (TTFF) in milliseconds.

rebufferRationumber

The rebuffering ratio for the asset.

errorRatenumber

The error rate for the stream/asset.

exitsBeforeStartnumber

The percentage of sessions that existed before the asset started playing.

Example response

[
  {
    "playbackId": "1bde4o2i6xycudoy",
    "creatorId": "john@doe.com",
    "viewerId": "1bde4o2i6xycudoy",
    "dStorageUrl": "ipfs://QmZ4",
    "timestamp": 1587667174725,
    "device": "iPhone",
    "deviceType": "mobile",
    "cpu": "ARM",
    "os": "iOS",
    "browser": "Safari",
    "browserEngine": "WebKit",
    "continent": "North America",
    "country": "United States",
    "subdivision": "California",
    "timezone": "America/Los_Angeles",
    "viewCount": 100,
    "playtimeMins": 10,
    "ttffMs": 100,
    "rebufferRatio": 0.1,
    "errorRate": 0.1,
    "exitsBeforeStart": 0.5
  }
]

Changes

  • fc477586b24cRevision changes
    • breaking

      the response property became optional for the status

  • d0909f9b9414Revision changes
    • warning

      removed the optional property / from the response with the status

    • info

      api operation id getViewershipMetrics was added

    • info

      api tag metrics added

    • info

      added the optional property / to the response with the status