GraphQL Analytics API

import { DashButton } from "~/components";

Stream provides analytics about both live video and video uploaded to Stream, via the GraphQL API described below, as well as on the Stream Analytics page of the Cloudflare dashboard.

The Stream Analytics API uses the Cloudflare GraphQL Analytics API, which can be used across many Cloudflare products. For more about GraphQL, rate limits, filters, and sorting, refer to the Cloudflare GraphQL Analytics API docs.

Getting started

1. In the Cloudflare dashboard, go to the Account API tokens page.

2. Generate an API token with the Account Analytics permission.

3. Use a GraphQL client of your choice to make your first query. Postman has a built-in GraphQL client which can help you run your first query and introspect the GraphQL schema to understand what is possible.

Refer to the sections below for available metrics, dimensions, fields, and example queries across multiple datasets.

Query Stream datasets under viewer.accounts. Use filter to select records and dimensions to group results.

Grouped datasets expose aggregates like avg, sum, and count. Raw datasets return fields directly, without an aggregate object.

Dotted field paths indicate nested selections: sum.minutesViewed means sum { minutesViewed }.

To find current fields and filter operators, explore the GraphQL schema using introspection. The following is a summary with explanations of useful fields.

Video delivered via HLS/DASH and WebRTC

Stream collects minutes of video delivered for live and on-demand video. These data include minutes delivered via HLS/DASH and WebRTC (WHEP), regardless of your player. This is a billable metric, but GraphQL data are sampled so it may not precisely match billable usage reported on invoices.

Use streamMinutesViewedAdaptiveGroups to query these delivery metrics.

Filters and dimensions

The dataset supports these filters and grouping dimensions:

Some filters, like date, can be used with operators, such as gt (greater than) and lt (less than), as shown in the example query below. For more advanced filtering options, refer to filtering.

Metrics

The dataset exposes these metrics:

Example

Get minutes viewed by country

query StreamGetMinutesExample($accountTag: string!, $start: Date, $end: Date) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			streamMinutesViewedAdaptiveGroups(
				filter: { date_geq: $start, date_lt: $end }
				orderBy: [sum_minutesViewed_DESC]
				limit: 100
			) {
				sum {
					minutesViewed
				}
				dimensions {
					uid
					clientCountryName
				}
			}
		}
	}
}

{
	"data": {
		"viewer": {
			"accounts": [
				{
					"streamMinutesViewedAdaptiveGroups": [
						{
							"dimensions": {
								"clientCountryName": "US",
								"uid": "<VIDEO_ID>"
							},
							"sum": {
								"minutesViewed": 2234
							}
						},
						{
							"dimensions": {
								"clientCountryName": "CN",
								"uid": "<VIDEO_ID>"
							},
							"sum": {
								"minutesViewed": 700
							}
						},
						{
							"dimensions": {
								"clientCountryName": "IN",
								"uid": "<VIDEO_ID>"
							},
							"sum": {
								"minutesViewed": 553
							}
						}
					]
				}
			]
		}
	},
	"errors": null
}

RTMP and SRT input metrics

Use these datasets to inspect RTMP or SRT inputs. Query liveInputEventsAdaptive for events and liveInputEventsAdaptiveGroups for stored segment metrics. These datasets are sampled, so consider using webhooks or Workers event subscriptions to receive events in realtime.

Event fields

liveInputEventsAdaptive returns event log fields directly, not segment metrics. It excludes events with an empty eventDescription.

You can select and filter these fields:

Filters and dimensions

liveInputEventsAdaptiveGroups contains only stored segment events. It supports these filters and grouping dimensions:

Metrics

A GOP (group of pictures) is a sequence of video frames. A "GOP size" is sometimes called a "keyframe interval." These metrics all relate to video segments for each GOP:

To estimate average broadcast bitrate, filter liveInputEventsAdaptiveGroups by inputId and the broadcast datetime range. Select avg.gopByteSize and avg.gopDuration in the same group.

Omit dimensions to get one result for the whole broadcast. For example, use avg.gopByteSize in bytes and avg.gopDuration in milliseconds to calculate bits per second:

bitrate_bps = 8000 * avg.gopByteSize / avg.gopDuration

Both averages use the same sampling weights, so their ratio estimates total bytes divided by total media duration. Only calculate the ratio when avg.gopDuration is greater than zero.

HLS/DASH quality of experience metrics

Common Media Client Data (CMCD) reports client-side playback measurements. Stream built-in players and supported custom players provide CMCD.

Use streamCMCDAdaptiveGroups to query quality of experience (QoE) metrics. These measurements describe player experience, not billable minutes delivered.

Filters and dimensions

The dataset supports these filters and grouping dimensions:

Metrics

The dataset exposes these aggregates:

Select percentile fields under quantiles. All durations are in milliseconds, and P999 means the 99.9th percentile:

WebRTC WHIP/WHEP metrics

Use streamWHIPBroadcastMetricsAdaptive and streamWHIPBroadcastMetricsAdaptiveGroups to inspect WebRTC-HTTP Ingestion Protocol (WHIP) ingest. For WebRTC-HTTP Egress Protocol (WHEP) playback, query minutes delivered.

Stream collects WHIP observations every 15 seconds. They can take two to three minutes to become queryable.

Raw fields

streamWHIPBroadcastMetricsAdaptive returns these fields directly. You can also use these fields in filters:

Filters and dimensions

streamWHIPBroadcastMetricsAdaptiveGroups supports these filters and grouping dimensions:

Metrics

The grouped dataset exposes these metrics. Select count directly, and nested fields under sum or avg:

Pagination

GraphQL API supports seek pagination: using filters, you can specify the last video UID so the response only includes data for videos after the last video UID.

The query returns data for two videos after $uId. Set $uId to the last video UID from the previous response:

query StreamPaginationExample(
	$accountTag: string!
	$start: Date
	$end: Date
	$uId: string
) {
	viewer {
		accounts(filter: { accountTag: $accountTag }) {
			streamMinutesViewedAdaptiveGroups(
				filter: { date_geq: $start, date_lt: $end, uid_gt: $uId }
				orderBy: [uid_ASC]
				limit: 2
			) {
				count
				sum {
					minutesViewed
				}
				dimensions {
					uid
				}
			}
		}
	}
}

Here are the steps to implementing pagination:

1. Call the first query without uid_gt filter to get the first set of videos
2. Grab the last video UID from the response from the first query
3. Call next query by specifying uid_gt property and set it to the last video UID. This will return the next set of videos

For more on pagination, refer to the Cloudflare GraphQL Analytics API docs.

Limitations

Query intervals and retention periods have dataset-specific defaults:

Use the settings node under viewer.accounts to check limits for your account. The maxDuration and notOlderThan fields report the query interval and retention period in seconds.