---
title: "Get the playback clients of active viewers with their current playback health"
method: GET
path: "/admin/viewers/playback"
tags: ["Internal", "Admin", "Video"]
---

# Get the playback clients of active viewers with their current playback health

`GET /admin/viewers/playback`

One entry per playback client currently watching, with the most recent playback measurements
for that client. Clients that report CMCD are identified by their player-supplied session ID,
which distinguishes players sharing an address; every other client is identified the same way
viewers are. A viewer with no playback measurements is still listed, with a null `playback`.

## Response `200`

List of active playback clients

- PlaybackClient[]
  - `clientID` string, required — Playback identity of the client. The player-supplied CMCD session ID when it provides one, otherwise the same request-derived identity used for viewers.
  - `viewerID` string, required — Request-derived identity of the viewer this client belongs to. Clients sharing an address and user agent share a viewer identity.
  - `firstSeen` string, date-time
  - `geo` GeoDetails
    - `countryCode` string
    - `regionName` string
    - `timeZone` string
  - `userAgent` string
  - `ipAddress` string
  - `playback` PlaybackClientHealth — The most recent playback measurements for one client. A measurement is null when it is unknown for this client rather than measured as zero, because not every player reports every value, server-side observation cannot measure latency at all, and a value the player has stopped reporting expires rather than standing in for the current one.
    - `source` 'client' | 'server', required — Whether the player is currently reporting its own playback, or the server is measuring it while serving segments. Individual values can still come from the other side, most often the segment download duration of a player that reports everything except how long its downloads took.
    - `lastUpdate` string, date-time, required — When the most recent measurement of any value for this client arrived.
    - `playerState` 'p' | 'a' | 'w' | 'k' | 'e' — Latest player state from CMCD, where p is playing, a is paused, w is buffering, k is seeking, and e is ended.
    - `measurementStatus` 'unmeasurable' — Explains why the server could not produce a trustworthy segment measurement.
    - `bandwidthKbps` number, double, nullable — How fast video is reaching the client, either the player's own throughput estimate or the rate at which the server served its most recent segment. Server-side measurement may be unavailable when the server cannot see a trustworthy transfer, so clients report null unless the player measures itself.
    - `latencySeconds` number, double, nullable — How far behind the live edge the client is playing. Only players that report it provide this, currently those supporting CMCD and those using the deprecated playback metrics endpoint.
    - `downloadSeconds` number, double, nullable — How long the client's most recent video segment took to transfer.
    - `bitrateKbps` number, double, nullable — Encoded bitrate of the quality variant the client is playing, as advertised in the stream playlist. That figure includes audio, so it is near but not equal to the configured video bitrate of the matching output variant. Only players that report it provide this.
    - `errorCount` number, double, nullable — Errors, including buffering, since this client started playing. Null for a client the server can only observe, which reveals nothing about the player's errors.
    - `qualityVariantChanges` number, double, nullable — Quality variant switches since this client started playing. Null when the client reveals nothing about the quality it is playing.

## Other responses

- `400` — Bad request
- `401` — Basic auth failure
- `default` — Unexpected error

---

[API](https://skmtc.net/owncast/apis/owncast-apis.md) · [All operations](https://skmtc.net/owncast/apis/owncast-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/owncast/owncast-apis/revisions/dc1c42f7f8f6/schema)