RTCPeerConnection.getStats()

The RTCPeerConnection method getStats() returns a promise which resolves with data providing statistics about either the overall connection or about the specified MediaStreamTrack.

Syntax

promise = rtcPeerConnection.getStats(selector)

Parameters

selector Optional
A MediaStreamTrack for which to gather statistics. If this is null (the default value), statistics will be gathered for the entire RTCPeerConnection.

Return value

A Promise which resolves with an RTCStatsReport object providing connection statistics. The contents of the report depend on the selector as well as other details of the connection.

Exceptions

This method does not throw exceptions; instead, it rejects the returned promise with one of the following errors:

InvalidAccessError
There is no RTCRtpSender or RTCRtpReceiver whose track matches the specified selector, or selector matches more than one sender or receiver.

Obsolete syntax

Previously, getStats() used success and failure callbacks to report the results to you, instead of using a promise. 

This version of getStats() is obsolete; in addition, the data it returns is entirely different from the current specification, and the form of that data was never documented. This form of getStats() has been or will soon be removed from most browsers; you should not use it, and should update existing code to use the new promise-based version. Check the Browser compatibility table to verify the state of this method.

promise = rtcPeerConnection.getStats(selector, successCallback, failureCallback)  

Parameters

selector Optional
A MediaStreamTrack for which to gather statistics. If this is null (the default value), statistics will be gathered for the entire RTCPeerConnection.
successCallback
A callback function to call when the stats have been retrieved. The function receives as input a single parameter: an RTCStatsReport with the collected statistics. No output is expected from the function.
failureCallback
A function to call when an error occurs while attempting to collect statistics. The callback receives as input the exception (a DOMException object describing the error which occurred. No return value is expected from the callback.

Example

This example creates a periodic function using setInterval() that collects statistics for an RTCPeerConnection every second, generating an HTML-formatted report and inserting it into a specific element in the DOM.

window.setInterval(function() {
  myPeerConnection.getStats(null).then(stats => {
    let statsOutput = "";

    stats.forEach(report => {
      statsOutput += `<h2>Report: ${report.type}</h3>\n<strong>ID:</strong> ${report.id}<br>\n` +
                     `<strong>Timestamp:</strong> ${report.timestamp}<br>\n`;
      
      // Now the statistics for this report; we intentially drop the ones we
      // sorted to the top above

      Object.keys(report).forEach(statName => {
        if (statName !== "id" && statName !== "timestamp" && statName !== "type") {
          statsOutput += `<strong>${statName}:</strong> ${report[statName]}<br>\n`;
        }
      });
    });

    document.querySelector(".stats-box").innerHTML = statsOutput;
  });
}, 1000);

This works by calling getStats(), then, when the promise is resolved, iterates over the RTCStats objects on the returned RTCStatsReport. A section is created for each report with a header and all of the statistics below, with the type, ID, and timestamp handled specially to place them at the top of the list.

Once the HTML for the report is generated, it is injected into the element whose class is "stats-box" by setting its innerHTML property.

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCPeerConnection.getStats()' in that specification.
Candidate Recommendation Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
getStatsChrome Full support 58
Notes
Full support 58
Notes
Notes Promise resolves with RTCStatsReport.
Full support 54
Notes
Notes Promise-based version.
Full support 24
Edge Full support 15Firefox Full support YesIE No support NoOpera Full support 45Safari Full support 11WebView Android Full support 58
Notes
Full support 58
Notes
Notes Promise resolves with RTCStatsReport.
Full support 54
Notes
Notes Promise-based version.
Full support Yes
Chrome Android Full support 58
Notes
Full support 58
Notes
Notes Promise resolves with RTCStatsReport.
Full support 54
Notes
Notes Promise-based version.
Full support Yes
Firefox Android Full support YesOpera Android Full support 43Safari iOS Full support YesSamsung Internet Android Full support Yes
Optional MediaStreamTrack argumentChrome Full support 67Edge ? Firefox ? IE No support NoOpera Full support 54Safari ? WebView Android Full support 67Chrome Android Full support 67Firefox Android ? Opera Android Full support 48Safari iOS ? Samsung Internet Android ?
Uses callbacks instead of promises
Deprecated
Chrome Full support 24Edge Full support 15Firefox No support 27 — 66IE No support NoOpera Full support 45Safari Full support 11WebView Android Full support YesChrome Android Full support YesFirefox Android ? Opera Android Full support 43Safari iOS ? Samsung Internet Android ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
Deprecated. Not for use in new websites.
Deprecated. Not for use in new websites.
See implementation notes.
See implementation notes.