Skip to main content

​
Overview

ConfigOptions is the TypeScript interface for the optional configuration object passed to new SpeedTest(config). Every field is optional — omitting a field uses the documented default. 
import SpeedTest from '@cloudflare/speedtest';
import type { ConfigOptions } from '@cloudflare/speedtest';

const config: ConfigOptions = {
  autoStart: false,
  bandwidthPercentile: 0.9,
};

const engine = new SpeedTest(config);

​
Engine control

​
autoStart
boolean
default:"true"
Whether to call play() automatically when the engine is instantiated. Set to false to construct the engine without starting measurements and call play() manually when ready.
// Construct now, start later
const engine = new SpeedTest({ autoStart: false });
document.getElementById('start')!.addEventListener('click', () => engine.play());

​
API endpoints

​
downloadApiUrl
string
default:"https://speed.cloudflare.com/__down"
URL used for download GET requests and latency probes. The engine appends a bytes query parameter to request files of specific sizes (e.g. ?bytes=1000000).
​
uploadApiUrl
string
default:"https://speed.cloudflare.com/__up"
URL used for upload POST requests. The engine posts binary payloads of specific sizes to this endpoint.
​
turnServerUri
string
default:"turn.speed.cloudflare.com:50000"
URI of the TURN server used for packet loss measurements. The engine connects to this server via WebRTC to send and receive UDP packets.
The default public TURN server is deprecated and will be discontinued. You must supply your own TURN server to get packet loss results. See the packet loss setup guide for instructions.
​
turnServerCredsApiUrl
string
URL of an endpoint that returns short-lived TURN server credentials as a JSON response. The response must include username and credential string fields and may optionally include a urls array of TURN server addresses. Used as an alternative to providing static credentials via turnServerUser and turnServerPass. See TURN server setup for a reference implementation.
This option is accepted by the constructor but is not yet included in the published TypeScript type definitions. Use a type assertion (config as any) if you encounter type errors.
​
turnServerUser
string
Static TURN server username. Use this together with turnServerPass when your TURN server requires static credentials.
​
turnServerPass
string
Static TURN server password. Use this together with turnServerUser when your TURN server requires static credentials.
​
includeCredentials
boolean
default:"false"
Whether to include cookies and HTTP authentication credentials in download and upload fetch requests (credentials: 'include'). Enable this if your API endpoints require authenticated requests.

​
Measurement control

​
measurements
MeasurementConfig[]
The ordered sequence of measurements the engine performs. Each element is a MeasurementConfig object with a type field plus type-specific fields.Omitting this field uses the built-in default sequence, which ramps up from small latency probes through progressively larger download and upload sizes, followed by a packet loss test.Each measurement type accepts the following fields:
FieldRequiredTypeDescription
typeyes"latency"Measurement type.
numPacketsyesnumberNumber of latency GET requests to perform against the download API with bytes=0. Round-trip TTFB is extracted from PerformanceResourceTiming.
​
measureDownloadLoadedLatency
boolean
default:"true"
Whether to measure latency in parallel with active download requests (loaded latency in the download direction). Results are accessible via results.getDownLoadedLatency().
​
measureUploadLoadedLatency
boolean
default:"true"
Whether to measure latency in parallel with active upload requests (loaded latency in the upload direction). Results are accessible via results.getUpLoadedLatency().
​
loadedLatencyThrottle
number
default:"400"
Minimum time in milliseconds to wait between loaded latency probe requests. Increasing this value reduces the number of latency samples collected during bandwidth measurements.
​
bandwidthFinishRequestDuration
number
default:"1000"
Target request duration in milliseconds. When the engine completes a download or upload measurement set and the observed request duration exceeds this value, it considers that transfer size sufficient and skips any remaining measurement sets for the same direction.This implements the ramp-up strategy: small file sizes are tested first, and once requests take long enough the engine stops increasing the file size.
​
bandwidthAbortRequestDuration
number
default:"0"
Maximum request duration in milliseconds before the engine aborts the current measurement set early and stops further measurements in that direction. A value of 0 disables early abort.Use this to cap test duration on very slow connections.
​
estimatedServerTime
number
default:"10"
Fixed server processing time in milliseconds subtracted from all time-to-first-byte calculations when the server does not return a Server-Timing response header. Adjust this if you use a custom API endpoint with a different processing baseline.

​
Result calculation

​
latencyPercentile
number
default:"0.5"
Percentile (between 0 and 1) used to reduce the set of raw latency measurements to a single value. The default of 0.5 returns the median. Lower values produce more optimistic results; higher values are more conservative.
​
bandwidthPercentile
number
default:"0.9"
Percentile (between 0 and 1) used to reduce the set of raw bandwidth measurements to a single value. The default of 0.9 reflects near-peak throughput while excluding outliers at the extreme high end.
​
bandwidthMinRequestDuration
number
default:"10"
Minimum request duration in milliseconds for a download or upload sample to be included in the bandwidth calculation. Samples from requests that complete faster than this threshold are discarded as unreliable.
​
loadedRequestMinDuration
number
default:"250"
Minimum request duration in milliseconds for a bandwidth request to be considered as genuinely loading the connection. Loaded latency samples are only recorded alongside requests that meet this threshold.
​
loadedLatencyMaxPoints
number
default:"20"
Maximum number of loaded latency data points to retain per direction. When more samples are available the most recent ones are kept and earlier ones are discarded.

​
TypeScript interface

export interface ConfigOptions {
  autoStart?: boolean;

  // APIs
  downloadApiUrl?: string;
  uploadApiUrl?: string;
  turnServerUri?: string;
  turnServerUser?: string;
  turnServerPass?: string;
  includeCredentials?: boolean;

  // Note: turnServerCredsApiUrl is also accepted but is not yet
  // reflected in the published TypeScript type definitions.

  // Measurements
  measurements?: MeasurementConfig[];
  measureDownloadLoadedLatency?: boolean;
  measureUploadLoadedLatency?: boolean;
  loadedLatencyThrottle?: number;
  bandwidthFinishRequestDuration?: number;
  bandwidthAbortRequestDuration?: number;
  estimatedServerTime?: number;

  // Result interpretation
  latencyPercentile?: number;
  bandwidthPercentile?: number;
  bandwidthMinRequestDuration?: number;
  loadedRequestMinDuration?: number;
  loadedLatencyMaxPoints?: number;
}

​
Example: latency-only test

import SpeedTest from '@cloudflare/speedtest';
import type { ConfigOptions } from '@cloudflare/speedtest';

const config: ConfigOptions = {
  autoStart: true,
  measurements: [
    { type: 'latency', numPackets: 20 },
  ],
  latencyPercentile: 0.5,
};

const engine = new SpeedTest(config);
engine.onFinish = results => {
  console.log('Latency:', results.getUnloadedLatency(), 'ms');
  console.log('Jitter:', results.getUnloadedJitter(), 'ms');
};

Build docs developers (and LLMs) love

Get started for freeTalk to us