Skip to main content
Pass a configuration object to the SpeedTest constructor to override any defaults. Every option is optional — omitting the config object entirely is valid. 
import SpeedTest from '@cloudflare/speedtest';

const engine = new SpeedTest({ autoStart: false });

​
Engine

​
autoStart
boolean
default:"true"
Whether to automatically start the measurements when the SpeedTest instance is created. Set to false to control start time manually using engine.play().

​
APIs

​
downloadApiUrl
string
default:"https://speed.cloudflare.com/__down"
The URL used for download GET requests. Each request appends a bytes query parameter specifying the response size.
​
uploadApiUrl
string
default:"https://speed.cloudflare.com/__up"
The URL used for upload POST requests. Each request posts a body of the configured byte size.
​
turnServerUri
string
default:"turn.speed.cloudflare.com:50000"
The URI of the TURN server used for packet loss measurement over WebRTC.
The public Cloudflare TURN server is deprecated and will be discontinued. You must provide your own TURN server to obtain packet loss results. See the packet loss measurement type for details.
​
turnServerCredsApiUrl
string
A URL that returns TURN server credentials as a JSON response with username and credential keys (and optionally a urls array of TURN server addresses). Used as an alternative to providing credentials directly via turnServerUser and turnServerPass. See TURN server setup for a complete example worker implementation.
​
turnServerUser
string
The username for TURN server authentication. Used together with turnServerPass to authenticate directly, without fetching credentials from turnServerCredsApiUrl.
​
turnServerPass
string
The password for TURN server authentication. Used together with turnServerUser.
​
includeCredentials
boolean
default:"false"
Whether to include cookies and other credentials with download and upload requests (sets credentials: 'include' on the underlying fetch calls). Useful when the test endpoints require session-based authentication.

​
Measurements

​
measurements
MeasurementConfig[]
The ordered sequence of measurements the engine will perform. Each entry is an object with a type field plus type-specific options. See Measurement types for the full reference and the default array.
​
measureDownloadLoadedLatency
boolean
default:"true"
Whether to perform additional latency requests in parallel with active download measurements. This produces a “loaded latency” value that reflects real-world latency under download load.
​
measureUploadLoadedLatency
boolean
default:"true"
Whether to perform additional latency requests in parallel with active upload measurements. This produces a “loaded latency” value that reflects real-world latency under upload load.
​
loadedLatencyThrottle
number
default:"400"
Minimum time in milliseconds to wait between consecutive loaded-latency requests. Reduces interference with the bandwidth measurement being run in parallel.
​
bandwidthFinishRequestDuration
number
default:"1000"
Duration threshold in milliseconds. When a download or upload request in a given direction takes at least this long, the engine stops executing subsequent measurement sets for that direction (ramp-up is considered complete). Set to 0 to disable early stopping and always run every configured measurement.
​
bandwidthAbortRequestDuration
number
default:"0"
Duration threshold in milliseconds. When a download or upload request exceeds this duration, the engine aborts the in-progress request early and stops further measurements in that direction. Defaults to 0 (disabled). Only set this when you want to cap total test time.
​
estimatedServerTime
number
default:"10"
A fixed duration in milliseconds subtracted from all time-to-first-byte calculations to discount server-side processing time. This value is only used when the download/upload API does not return a server-timing response header containing the actual server processing time.

​
Result interpretation

​
latencyPercentile
number
default:"0.5"
The percentile (between 0 and 1) used to derive a single latency value from the collected set of latency measurements. The default of 0.5 is the median.
​
bandwidthPercentile
number
default:"0.9"
The percentile (between 0 and 1) used to derive a single bandwidth value from the collected set of bandwidth measurements. The default of 0.9 selects a near-peak value, filtering out outlier-low samples.
​
bandwidthMinRequestDuration
number
default:"10"
Minimum duration in milliseconds a request must last for its result to be included in the bandwidth calculation. Requests that complete faster than this threshold are considered too short to produce reliable measurements.
​
loadedRequestMinDuration
number
default:"250"
Minimum duration in milliseconds a bandwidth request must last for the simultaneous loaded-latency samples captured during it to be counted. Shorter requests are not considered to be genuinely loading the connection.
​
loadedLatencyMaxPoints
number
default:"20"
Maximum number of loaded-latency data points to retain per direction. When more samples are collected than this limit, only the most recent ones are kept.

​
Complete configuration example

The example below disables auto-start, points at a custom TURN server for packet loss measurement, and tightens the bandwidth ramp-up threshold. 
import SpeedTest from '@cloudflare/speedtest';

const engine = new SpeedTest({
  // Start manually
  autoStart: false,

  // Custom TURN server for packet loss measurement
  turnServerUri: 'turn.example.com:3478',
  turnServerCredsApiUrl: 'https://example.com/turn-creds',

  // Alternatively, provide credentials directly:
  // turnServerUser: 'my-user',
  // turnServerPass: 'my-password',

  // Ramp up faster — stop bandwidth measurement sets after 750 ms
  bandwidthFinishRequestDuration: 750,

  // Only keep the top-95th-percentile bandwidth sample
  bandwidthPercentile: 0.95,
});

engine.onFinish = results => {
  console.log(results.getSummary());
};

// Start the test when ready
engine.play();
When autoStart is false, the engine will not make any network requests until engine.play() is called. This lets you set up event listeners and configure the UI before any measurements begin.

Build docs developers (and LLMs) love

Get started for freeTalk to us