RTCStatsReport

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Some parts of this feature may have varying levels of support.

The RTCStatsReport interface of the WebRTC API provides a statistics report for a RTCPeerConnection, RTCRtpSender, or RTCRtpReceiver.

An RTCStatsReport instance is a read-only Map-like object, in which each key is an identifier for an object for which statistics are being reported, and the corresponding value is a dictionary object providing the statistics.

Instance properties

RTCStatsReport.size

Returns the number of items in the RTCStatsReport object.

Instance methods

RTCStatsReport.entries()

Returns a new Iterator object that contains a two-member array of [id, statistic-dictionary] for each element in the RTCStatsReport object, in insertion order.

RTCStatsReport.forEach()

Calls callbackFn once for each key-value pair present in the RTCStatsReport object, in insertion order. If a thisArg parameter is provided to forEach, it will be used as the this value for each callback.

RTCStatsReport.get()

Returns the statistics dictionary associated with the passed id, or undefined if there is none.

RTCStatsReport.has()

Returns a boolean indicating whether the RTCStatsReport contains a statistics dictionary associated with the specified id.

RTCStatsReport.keys()

Returns a new Iterator object that contains the keys (IDs) for each element in the RTCStatsReport object, in insertion order.

RTCStatsReport.values()

Returns a new Iterator object that contains the values (statistics object) for each element in the RTCStatsReport object, in insertion order.

RTCStatsReport[Symbol.iterator]()

Returns a new Iterator object that contains a two-member array of [id, statistic-dictionary] for each element in the RTCStatsReport object, in insertion order.

Description

A Promise that resolves to an RTCStatsReport is returned from the RTCRtpReceiver.getStats(), RTCRtpSender.getStats() and RTCPeerConnection.getStats() methods. Calling getStats() on an RTCPeerConnection lets you specify whether you wish to obtain outbound statistics, inbound statistics, or statistics for the whole connection. The RTCRtpReceiver and RTCRtpSender versions of getStats() only return inbound and outbound statistics, respectively.

The statistics report is a read-only Map-like object: an ordered dictionary, where the properties are id strings that uniquely identify the WebRTC object that was inspected to produce a particular set of statistics, and the value is a dictionary object containing those statistics. A RTCStatsReport can be iterated and used the same ways as a read-only Map.

The report may contain many different categories of statistics, including inbound and outbound statistics for both the current and remote ends of the peer connection, information about codecs, certificates and media used, and so on. Each category of statistic is provided in a different type of statistics dictionary object, which can be identified from its type property.

Common instance properties

All the dictionary types have the following properties:

id

A string that uniquely identifies the object was monitored to produce the set of statistics. This value persists across reports for (at least) the lifetime of the connection. Note however that for some statistics the ID may vary between browsers and for subsequent connections, even to the same peer.

timestamp

A high resolution timestamp object (DOMHighResTimeStamp) object indicating the time at which the sample was taken. Many reported statistics are cumulative values; the timestamp allows rates and averages to be calculated between any two reports, at any desired reporting rate.

type

A string with a value that indicates the type of statistics that the object contains, such as candidate-pair, inbound-rtp, certificate, and so on. The types of statistics and their corresponding objects are listed below.

Users typically iterate a RTCStatsReport, using a forEach() or for...of loop, selecting the statistics of interest using the type property. Once a particular statistic object has been identified using its type, the id property can subsequently be used with get() to obtain the same statistic report at a different time.

The timestamp can be used to calculate average values for statistics that accumulate over the lifetime of a connection.

The statistic types

The statistics type values and their corresponding dictionaries are listed below.

type Dictionary Description
candidate-pair RTCIceCandidatePairStats Statistics describing the change from one RTCIceTransport to another, such as during an ICE restart.
certificate RTCCertificateStats Statistics about a certificate being used by an RTCIceTransport.
codec RTCCodecStats Statistics about a specific codec being used by streams being sent or received by this connection.
data-channel RTCDataChannelStats Statistics related to one RTCDataChannel on the connection.
inbound-rtp RTCInboundRtpStreamStats Statistics describing the state of one of the connection's inbound data streams.
local-candidate RTCIceCandidateStats Statistics about a local ICE candidate associated with the connection's RTCIceTransports.
media-source RTCAudioSourceStats or RTCVideoSourceStats Statistics about the media produced by the MediaStreamTrack attached to an RTP sender. The dictionary this key maps to depends on the track's kind.
outbound-rtp RTCOutboundRtpStreamStats Statistics describing the state of one of the outbound data streams on this connection.
peer-connection RTCPeerConnectionStats Statistics describing the state of the RTCPeerConnection.
remote-candidate RTCIceCandidateStats Statistics about a remote ICE candidate associated with the connection's RTCIceTransports.
remote-inbound-rtp RTCRemoteInboundRtpStreamStats Statistics describing the state of the inbound data stream from the perspective of the remote peer.
remote-outbound-rtp RTCRemoteOutboundRtpStreamStats Statistics describing the state of the outbound data stream from the perspective of the remote peer.
transport RTCTransportStats Statistics about a transport used by the connection.

Examples

Iterate report from an RTCPeerConnection using forEach loop

This example logs shows how you might log video-related statistics for the local RTCRtpReceiver responsible for receiving streamed media.

Given a variable myPeerConnection, which is an instance of RTCPeerConnection, the code uses await to wait for the statistics report, and then iterates it using RTCStatsReport.forEach(). It then filters the dictionaries for just those reports that have the type of inbound-rtp and kind of video.

js
const stats = await myPeerConnection.getStats();

stats.forEach((report) => {
  if (report.type === "inbound-rtp" && report.kind === "video") {
    // Log the frame rate
    console.log(report.framesPerSecond);
  }
});

Iterate report from an RTCRtpSender using a for...of loop

This example shows how you might iterate the outbound statistics from an RTCRtpSender.

The code follows a similar pattern to the previous example, but iterates using a for...of-loop on the RTCStatsReport.values(), and filters on the type of outbound-rtp. It assumes you already have an RTCRtpSender object named "sender".

js
const stats = await sender.getStats();

for (const stat of stats.values()) {
  if (stat.type != "outbound-rtp") continue;
  Object.keys(stat).forEach((statName) => {
    console.log(`${statName}: ${report[statName]}`);
  });
}

Specifications

Specification
WebRTC: Real-Time Communication in Browsers
# rtcstatsreport-object

Browser compatibility

Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
RTCStatsReport
[Symbol.iterator]
entries
forEach
get
has
keys
size
candidate-pair stats
availableOutgoingBitrate in 'candidate-pair' stats
bytesDiscardedOnSend in 'candidate-pair' stats
Experimental
bytesReceived in 'candidate-pair' stats
bytesSent in 'candidate-pair' stats
consentRequestsSent in 'candidate-pair' stats
Experimental
currentRoundTripTime in 'candidate-pair' stats
id in 'candidate-pair' stats
lastPacketReceivedTimestamp in 'candidate-pair' stats
lastPacketSentTimestamp in 'candidate-pair' stats
localCandidateId in 'candidate-pair' stats
nominated in 'candidate-pair' stats
packetsDiscardedOnSend in 'candidate-pair' stats
Experimental
packetsReceived in 'candidate-pair' stats
Experimental
packetsSent in 'candidate-pair' stats
Experimental
priority in 'candidate-pair' stats
DeprecatedNon-standard
remoteCandidateId in 'candidate-pair' stats
requestsReceived in 'candidate-pair' stats
requestsSent in 'candidate-pair' stats
responsesReceived in 'candidate-pair' stats
responsesSent in 'candidate-pair' stats
state in 'candidate-pair' stats
timestamp in 'candidate-pair' stats
totalRoundTripTime in 'candidate-pair' stats
transportId in 'candidate-pair' stats
type in 'candidate-pair' stats
certificate stats
base64Certificate in 'certificate' stats
fingerprint in 'certificate' stats
fingerprintAlgorithm in 'certificate' stats
id in 'certificate' stats
timestamp in 'certificate' stats
type in 'certificate' stats
codec stats
channels in 'codec' stats
clockRate in 'codec' stats
id in 'codec' stats
mimeType in 'codec' stats
payloadType in 'codec' stats
sdpFmtpLine in 'codec' stats
timestamp in 'codec' stats
transportId in 'codec' stats
type in 'codec' stats
data-channel stats
bytesReceived in 'data-channel' stats
bytesSent in 'data-channel' stats
dataChannelIdentifier in 'data-channel' stats
id in 'data-channel' stats
label in 'data-channel' stats
messagesReceived in 'data-channel' stats
messagesSent in 'data-channel' stats
protocol in 'data-channel' stats
state in 'data-channel' stats
timestamp in 'data-channel' stats
type in 'data-channel' stats
inbound-rtp stats
audioLevel in 'inbound-rtp' stats
bytesReceived in 'inbound-rtp' stats
codecId in 'inbound-rtp' stats
concealedSamples in 'inbound-rtp' stats
concealmentEvents in 'inbound-rtp' stats
fecPacketsDiscarded in 'inbound-rtp' stats
fecPacketsReceived in 'inbound-rtp' stats
frameHeight in 'inbound-rtp' stats
frameWidth in 'inbound-rtp' stats
framesDecoded in 'inbound-rtp' stats
framesPerSecond in 'inbound-rtp' stats
framesReceived in 'inbound-rtp' stats
headerBytesReceived in 'inbound-rtp' stats
id in 'inbound-rtp' stats
insertedSamplesForDeceleration in 'inbound-rtp' stats
jitter in 'inbound-rtp' stats
jitterBufferDelay in 'inbound-rtp' stats
jitterBufferEmittedCount in 'inbound-rtp' stats
jitterBufferMinimumDelay in 'inbound-rtp' stats
Experimental
jitterBufferTargetDelay in 'inbound-rtp' stats
Experimental
keyFramesDecoded in 'inbound-rtp' stats
Experimental
kind in 'inbound-rtp' stats
lastPacketReceivedTimestamp in 'inbound-rtp' stats
mid in 'inbound-rtp' stats
nackCount in 'inbound-rtp' stats
packetsDiscarded in 'inbound-rtp' stats
packetsLost in 'inbound-rtp' stats
packetsReceived in 'inbound-rtp' stats
playoutId in 'inbound-rtp' stats
Experimental
qpSum in 'inbound-rtp' stats
type_inbound-rtp.remoteId
removedSamplesForAcceleration in 'inbound-rtp' stats
silentConcealedSamples in 'inbound-rtp' stats
ssrc in 'inbound-rtp' stats
timestamp in 'inbound-rtp' stats
totalAudioEnergy in 'inbound-rtp' stats
totalDecodeTime in 'inbound-rtp' stats
totalInterFrameDelay in 'inbound-rtp' stats
totalProcessingDelay in 'inbound-rtp' stats
totalSamplesDuration in 'inbound-rtp' stats
totalSamplesReceived in 'inbound-rtp' stats
totalSquaredInterFrameDelay in 'inbound-rtp' stats
trackIdentifier in 'inbound-rtp' stats
transportId in 'inbound-rtp' stats
type in 'inbound-rtp' stats
local-candidate stats
address in 'local-candidate' stats
candidateType in 'local-candidate' stats
foundation in 'local-candidate' stats
Experimental
id in 'local-candidate' stats
port in 'local-candidate' stats
priority in 'local-candidate' stats
protocol in 'local-candidate' stats
timestamp in 'local-candidate' stats
transportId in 'local-candidate' stats
type in 'local-candidate' stats
usernameFragment in 'local-candidate' stats
Experimental
media-playout stats
id in 'media-playout' stats
Experimental
kind in 'media-playout' stats
Experimental
synthesizedSamplesDuration in 'media-playout' stats
Experimental
synthesizedSamplesEvents in 'media-playout' stats
Experimental
timestamp in 'media-playout' stats
Experimental
totalPlayoutDelay in 'media-playout' stats
Experimental
totalSamplesCount in 'media-playout' stats
Experimental
totalSamplesDuration in 'media-playout' stats
Experimental
type in 'media-playout' stats
Experimental
media-source stats
audioLevel in 'media-source' stats
Experimental
frames in 'media-source' stats for video
framesPerSecond in 'media-source' stats for video
height in 'media-source' stats for video
id in 'media-source' stats
kind in 'media-source' stats
timestamp in 'media-source' stats
totalAudioEnergy in 'media-source' stats
Experimental
totalSamplesDuration in 'media-source' stats
Experimental
trackIdentifier in 'media-source' stats
type in 'media-source' stats
width in 'media-source' stats for video
outbound-rtp stats
active in 'outbound-rtp' stats
Experimental
bytesSent in 'outbound-rtp' stats
codecId in 'outbound-rtp' stats
frameHeight in 'outbound-rtp' stats
frameWidth in 'outbound-rtp' stats
framesEncoded in 'outbound-rtp' stats
framesPerSecond in 'outbound-rtp' stats
framesSent in 'outbound-rtp' stats
headerBytesSent in 'outbound-rtp' stats
id in 'outbound-rtp' stats
keyFramesEncoded in 'outbound-rtp' stats
Experimental
kind in 'outbound-rtp' stats
mediaSourceId in 'outbound-rtp' stats
mid in 'outbound-rtp' stats
nackCount in 'outbound-rtp' stats
packetsSent in 'outbound-rtp' stats
qpSum in 'outbound-rtp' stats
qualityLimitationDurations in 'outbound-rtp' stats
Experimental
qualityLimitationReason in 'outbound-rtp' stats
Experimental
remoteId in 'outbound-rtp' stats
retransmittedBytesSent in 'outbound-rtp' stats
retransmittedPacketsSent in 'outbound-rtp' stats
rid in 'outbound-rtp' stats
scalabilityMode in 'outbound-rtp' stats
Experimental
ssrc in 'outbound-rtp' stats
targetBitrate in 'outbound-rtp' stats
timestamp in 'outbound-rtp' stats
totalEncodeTime in 'outbound-rtp' stats
totalEncodedBytesTarget in 'outbound-rtp' stats
Experimental
totalPacketSendDelay in 'outbound-rtp' stats
transportId in 'outbound-rtp' stats
type in 'outbound-rtp' stats
peer-connection stats
dataChannelsClosed in 'peer-connection' stats
dataChannelsOpened in 'peer-connection' stats
id in 'peer-connection' stats
timestamp in 'peer-connection' stats
type in 'peer-connection' stats
remote-candidate stats
address in 'remote-candidate' stats
candidateType in 'remote-candidate' stats
foundation in 'remote-candidate' stats
Experimental
id in 'remote-candidate' stats
port in 'remote-candidate' stats
priority in 'remote-candidate' stats
protocol in 'remote-candidate' stats
timestamp in 'remote-candidate' stats
transportId in 'remote-candidate' stats
type in 'remote-candidate' stats
usernameFragment in 'remote-candidate' stats
Experimental
remote-inbound-rtp stats
codecId in 'remote-inbound-rtp' stats
fractionLost in 'remote-inbound-rtp' stats
id in 'remote-inbound-rtp' stats
jitter in 'remote-inbound-rtp' stats
kind in 'remote-inbound-rtp' stats
localId in 'remote-inbound-rtp' stats
packetsLost in 'remote-inbound-rtp' stats
packetsReceived in 'remote-inbound-rtp' stats
Experimental
roundTripTime in 'remote-inbound-rtp' stats
roundTripTimeMeasurements in 'remote-inbound-rtp' stats
ssrc in 'remote-inbound-rtp' stats
timestamp in 'remote-inbound-rtp' stats
totalRoundTripTime in 'remote-inbound-rtp' stats
transportId in 'remote-inbound-rtp' stats
type in 'remote-inbound-rtp' stats
remote-outbound-rtp stats
bytesSent in 'remote-outbound-rtp' stats
codecId in 'remote-outbound-rtp' stats
id in 'remote-outbound-rtp' stats
kind in 'remote-outbound-rtp' stats
localId in 'remote-outbound-rtp' stats
packetsSent in 'remote-outbound-rtp' stats
remoteTimestamp in 'remote-outbound-rtp' stats
reportsSent in 'remote-outbound-rtp' stats
Experimental
roundTripTimeMeasurements in 'remote-outbound-rtp' stats
Experimental
ssrc in 'remote-outbound-rtp' stats
timestamp in 'remote-outbound-rtp' stats
totalRoundTripTime in 'remote-outbound-rtp' stats
Experimental
transportId in 'remote-outbound-rtp' stats
type in 'remote-outbound-rtp' stats
transport stats
bytesReceived in 'transport' stats
bytesSent in 'transport' stats
dtlsCipher in 'transport' stats
dtlsRole in 'transport' stats
Experimental
dtlsState in 'transport' stats
iceLocalUsernameFragment in 'transport' stats
Experimental
iceRole in 'transport' stats
Experimental
iceState in 'transport' stats
Experimental
id in 'transport' stats
localCertificateId in 'transport' stats
packetsReceived in 'transport' stats
Experimental
packetsSent in 'transport' stats
Experimental
remoteCertificateId in 'transport' stats
selectedCandidatePairChanges in 'transport' stats
selectedCandidatePairId in 'transport' stats
srtpCipher in 'transport' stats
timestamp in 'transport' stats
tlsVersion in 'transport' stats
type in 'transport' stats
values

See also