---
title: "Query viewership metrics"
method: GET
path: "/data/views/query"
tags: ["metrics"]
---

# Query viewership metrics

`GET /data/views/query`

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

## Query parameters

- `playbackId` string
- `from` union
  - string, date-time
  - integer
- `to` union
  - string, date-time
  - integer
- `timeStep` 'hour' | 'day' | 'week' | 'month' | 'year'
- `assetId` string
- `streamId` string
- `creatorId` string
- `breakdownBy[]` string[]

## Response `200`

A list of Metric objects

- ViewershipMetric[]
  - `playbackId` string — The playback ID associated with the metric.
  - `creatorId` string — The ID of the creator associated with the metric.
  - `viewerId` string — The ID of the viewer associated with the metric.
  - `dStorageUrl` string — The URL of the distributed storage used for the asset
  - `timestamp` number — 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.
  - `device` string — The device used by the viewer.
  - `deviceType` string — The type of the device used by the viewer.
  - `cpu` string — The CPU used by the viewer's device.
  - `os` string — The operating system used by the viewer.
  - `browser` string — The browser used by the viewer.
  - `browserEngine` string — The browser engine used by the viewer's browser.
  - `continent` string — The continent where the viewer is located.
  - `country` string — The country where the viewer is located.
  - `subdivision` string — The subdivision (e.g., state or province) where the viewer is located.
  - `timezone` string — The timezone where the viewer is located.
  - `geohash` string — Geographic encoding of the viewers location. Accurate to 3 digits.
  - `viewCount` integer, required — The number of views for the stream/asset.
  - `playtimeMins` number, required — The total playtime in minutes for the stream/asset.
  - `ttffMs` number — The time-to-first-frame (TTFF) in milliseconds.
  - `rebufferRatio` number — The rebuffering ratio for the asset.
  - `errorRate` number — The error rate for the stream/asset.
  - `exitsBeforeStart` number — The percentage of sessions that existed before the asset started playing.

## Other responses

- `default` — Error

## Changes

- **2024-05-17** `fc477586b24c` — 1 breaking
  - the response property `errors` became optional for the status `default`
- **2024-04-23** `d0909f9b9414` — 1 warning, 3 info
  - removed the optional property `items/geohas` from the response with the `200` status
  - api operation id `getViewershipMetrics` was added
  - api tag `metrics` added
  - added the optional property `items/geohash` to the response with the `200` status

[Change history](https://skmtc.dev/livepeer/apis/livepeer-api-reference/changes/data/views/query/get.md)

---

[API](https://skmtc.dev/livepeer/apis/livepeer-api-reference.md) · [All operations](https://skmtc.dev/livepeer/apis/livepeer-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/livepeer/livepeer-api-reference/revisions/0d7e15217608/schema)