Stream Viewer Statistics

Returns aggregated statistics about viewers watching a specific stream, including distribution charts for various metrics.

Request

Property	Value
Method	`GET`
URL	`/api/streams/{appName}/{streamKey}/viewers/stats`
Content-Type	`application/json`
Authentication	Bearer Token

Request

bash

curl -X GET "{BASE_URL}/api/streams/{appName}/{streamKey}/viewers/stats" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

Parameter	Type	Required	Description
`appName`	string	Yes	Application name
`streamKey`	string	Yes	Stream key

Request

bash

curl -X GET "{BASE_URL}/api/streams/{appName}/{streamKey}/viewers/stats" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

Parameter	Type	Required	Default	Description
`harnessType`	string	No	-	Filter by harness type
`deviceType`	string	No	-	Filter by device type

With query parameters

bash

curl -X GET "{BASE_URL}/api/streams/{appName}/{streamKey}/viewers/stats?harnessType=value&deviceType=value" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Body

Pie Charts

Browser Chart

Parameter	Type	Description
`data.pieCharts.browser`	object	Distribution by browser
`data.pieCharts.browser.series`	integer[]	Count of viewers per browser
`data.pieCharts.browser.labels`	string[]	Browser names

Harness Type Chart

Parameter	Type	Description
`data.pieCharts.harness`	object	Distribution by harness type
`data.pieCharts.harness.series`	integer[]	Count of viewers per harness
`data.pieCharts.harness.labels`	string[]	Harness type names

Health Grade Chart

Parameter	Type	Description
`data.pieCharts.healthGrade`	object	Distribution by health grade
`data.pieCharts.healthGrade.series`	integer[]	Count of viewers per health grade
`data.pieCharts.healthGrade.labels`	string[]	Health grade labels

Quality Level Chart

Parameter	Type	Description
`data.pieCharts.qualityLevel`	object	Distribution by quality level
`data.pieCharts.qualityLevel.series`	integer[]	Count of viewers per quality level
`data.pieCharts.qualityLevel.labels`	string[]	Quality level labels

Operating System Chart

Parameter	Type	Description
`data.pieCharts.operatingSystem`	object	Distribution by OS
`data.pieCharts.operatingSystem.series`	integer[]	Count of viewers per OS
`data.pieCharts.operatingSystem.labels`	string[]	Operating system names

Device Type Chart

Parameter	Type	Description
`data.pieCharts.device`	object	Distribution by device type
`data.pieCharts.device.series`	integer[]	Count of viewers per device type
`data.pieCharts.device.labels`	string[]	Device type labels

Buffer Stability Chart

Parameter	Type	Description
`data.pieCharts.bufferStability`	object	Distribution by buffer stability
`data.pieCharts.bufferStability.series`	integer[]	Count of viewers per stability level
`data.pieCharts.bufferStability.labels`	string[]	Buffer stability labels

Bandwidth Stability Chart

Parameter	Type	Description
`data.pieCharts.bandwidthStability`	object	Distribution by bandwidth stability
`data.pieCharts.bandwidthStability.series`	integer[]	Count of viewers per stability level
`data.pieCharts.bandwidthStability.labels`	string[]	Bandwidth stability labels

Bar Charts

Duration Chart

Parameter	Type	Description
`data.barCharts.duration`	object	Session duration distribution
`data.barCharts.duration.unit`	string	Unit of measurement (`"s"`)
`data.barCharts.duration.mean`	number\|null	Mean duration across all viewers
`data.barCharts.duration.median`	number\|null	Median duration across all viewers
`data.barCharts.duration.series`	integer[]	Count of viewers per category
`data.barCharts.duration.categories`	object[]	Category definitions
`data.barCharts.duration.categories[].range`	string	Range description (e.g., `"0-10 s"`)
`data.barCharts.duration.categories[].label`	string	Human-readable label (e.g., `"Ultra short"`)

Bandwidth Chart

Parameter	Type	Description
`data.barCharts.bandwidth`	object	Bandwidth distribution
`data.barCharts.bandwidth.unit`	string	Unit of measurement (`"kbps"`)
`data.barCharts.bandwidth.mean`	number\|null	Mean bandwidth across all viewers
`data.barCharts.bandwidth.median`	number\|null	Median bandwidth across all viewers
`data.barCharts.bandwidth.series`	integer[]	Count of viewers per category
`data.barCharts.bandwidth.categories`	object[]	Category definitions
`data.barCharts.bandwidth.categories[].range`	string	Range description (e.g., `"0-500 kbps"`)
`data.barCharts.bandwidth.categories[].label`	string	Human-readable label (e.g., `"Ultra low"`)

Latency Chart

Parameter	Type	Description
`data.barCharts.latency`	object	Latency distribution
`data.barCharts.latency.unit`	string	Unit of measurement (`"ms"`)
`data.barCharts.latency.mean`	number\|null	Mean latency across all viewers
`data.barCharts.latency.median`	number\|null	Median latency across all viewers
`data.barCharts.latency.series`	integer[]	Count of viewers per category
`data.barCharts.latency.categories`	object[]	Category definitions
`data.barCharts.latency.categories[].range`	string	Range description (e.g., `"0-10 ms"`)
`data.barCharts.latency.categories[].label`	string	Human-readable label (e.g., `"Ultra low"`)

Buffer Size Chart

Parameter	Type	Description
`data.barCharts.bufferSize`	object	Buffer size distribution
`data.barCharts.bufferSize.unit`	string	Unit of measurement (`"ms"`)
`data.barCharts.bufferSize.mean`	number\|null	Mean buffer size across all viewers
`data.barCharts.bufferSize.median`	number\|null	Median buffer size across all viewers
`data.barCharts.bufferSize.series`	integer[]	Count of viewers per category
`data.barCharts.bufferSize.categories`	object[]	Category definitions
`data.barCharts.bufferSize.categories[].range`	string	Range description (e.g., `"0-250 ms"`)
`data.barCharts.bufferSize.categories[].label`	string	Human-readable label (e.g., `"Ultra low"`)

Metadata

Parameter	Type	Description
`meta.executionTime`	integer	Request processing time in milliseconds
`meta.generatedAt`	integer	Response generation timestamp (Unix timestamp in ms)

Successful Response (200)

json

{
  "data": {
    "pieCharts": {
      "browser": {
        "series": [1],
        "labels": ["Chrome"]
      },
      "harness": {
        "series": [1],
        "labels": ["STORM_MSE_VIEWER"]
      },
      "bufferStability": {
        "series": [1],
        "labels": ["GOOD"]
      },
      "healthGrade": {
        "series": [1],
        "labels": ["No Data"]
      },
      "qualityLevel": {
        "series": [1],
        "labels": ["native"]
      },
      "bandwidthStability": {
        "series": [1],
        "labels": ["STABLE"]
      },
      "operatingSystem": {
        "series": [1],
        "labels": ["Windows 10/11"]
      },
      "device": {
        "series": [1],
        "labels": ["DESKTOP"]
      }
    },
    "barCharts": {
      "duration": {
        "unit": "s",
        "mean": 8,
        "median": 8,
        "series": [1, 0, 0, 0, 0, 0, 0],
        "categories": [
          { "range": "0-10 s", "label": "Ultra short" },
          { "range": "11-60 s", "label": "Very short" },
          { "range": "61-300 s", "label": "Short" },
          { "range": "301-600 s", "label": "Medium" },
          { "range": "601-1800 s", "label": "Long" },
          { "range": "1801-3600 s", "label": "Very long" },
          { "range": "3600+ s", "label": "Extreme" }
        ]
      },
      "bandwidth": {
        "unit": "kbps",
        "mean": 443,
        "median": 443,
        "series": [1, 0, 0, 0, 0, 0, 0],
        "categories": [
          { "range": "0-500 kbps", "label": "Ultra low" },
          { "range": "501-1000 kbps", "label": "Very low" },
          { "range": "1001-2000 kbps", "label": "Low" },
          { "range": "2001-3000 kbps", "label": "Medium" },
          { "range": "3001-5000 kbps", "label": "High" },
          { "range": "5001-8000 kbps", "label": "Very high" },
          { "range": "8000+ kbps", "label": "Ultra high" }
        ]
      },
      "latency": {
        "unit": "ms",
        "mean": 20,
        "median": 20,
        "series": [0, 1, 0, 0, 0, 0, 0],
        "categories": [
          { "range": "0-10 ms", "label": "Ultra low" },
          { "range": "11-25 ms", "label": "Very low" },
          { "range": "26-50 ms", "label": "Low" },
          { "range": "51-100 ms", "label": "Medium" },
          { "range": "101-200 ms", "label": "High" },
          { "range": "201-500 ms", "label": "Very high" },
          { "range": "500+ ms", "label": "Critical" }
        ]
      },
      "bufferSize": {
        "unit": "ms",
        "mean": 19,
        "median": 19,
        "series": [1, 0, 0, 0, 0, 0, 0, 0],
        "categories": [
          { "range": "0-250 ms", "label": "Ultra low" },
          { "range": "251-350 ms", "label": "Very low" },
          { "range": "351-500 ms", "label": "Low" },
          { "range": "501-750 ms", "label": "Medium" },
          { "range": "751-1000 ms", "label": "High" },
          { "range": "1001-1500 ms", "label": "Very high" },
          { "range": "1501-2000 ms", "label": "Ultra high" },
          { "range": "2000+ ms", "label": "Extreme" }
        ]
      }
    }
  },
  "meta": {
    "executionTime": 1,
    "generatedAt": 1764763133517
  }
}

Error Response (4xx/5xx)

Parameter	Type	Description
`message`	string	Human-readable error message

json

{
  "message": "Error message"
}

Support Needed?

Create a free ticket and our support team will provide you necessary assistance.