Speed Test API¶

The Speed Test API provides endpoints for measuring internet connection speed, including download, upload, and latency metrics.

GET /speedtest/ping¶

Minimal latency endpoint for measuring round-trip time (RTT).

Response¶

{
  "ts": 1735550400000
}

Example¶

curl https://ods-api.m-8b1.workers.dev/speedtest/ping

GET /speedtest/download¶

Streams random data for download speed testing.

Query Parameters¶

Parameter	Type	Default	Description
`bytes`	number	10000000	Number of bytes to download (max 100MB)
`fast`	string	-	Set to `1` to enable fast mode (smaller chunks, reused data)

Fast Mode¶

When fast=1 is specified, the endpoint optimizes for HTTP/3 (QUIC):

Uses 16KB chunks instead of 64KB for faster first-byte
Reuses pre-generated random data to reduce CPU overhead
Better suited for shorter, more frequent tests

Response¶

Binary stream of random data with Content-Type: application/octet-stream.

Example¶

# Standard download (10MB)
curl -o /dev/null https://ods-api.m-8b1.workers.dev/speedtest/download?bytes=10000000

# Fast mode download (5MB with optimizations)
curl -o /dev/null https://ods-api.m-8b1.workers.dev/speedtest/download?bytes=5000000&fast=1

POST /speedtest/upload¶

Receives upload data and returns transfer statistics.

Request Body¶

Binary data (any content type).

Response¶

{
  "bytesReceived": 5000000,
  "durationMs": 1250,
  "mbps": 32.0
}

Example¶

# Upload 5MB of random data
dd if=/dev/urandom bs=1M count=5 2>/dev/null | \
  curl -X POST --data-binary @- https://ods-api.m-8b1.workers.dev/speedtest/upload

GET /speedtest/info¶

Returns server and client information for the current connection.

Response¶

{
  "server": {
    "location": "SJC",
    "region": "US"
  },
  "client": {
    "ip": "203.0.113.42",
    "location": "San Francisco, US",
    "asn": "AS7922",
    "isp": "Comcast Cable Communications"
  }
}

Example¶

curl https://ods-api.m-8b1.workers.dev/speedtest/info

POST /speedtest/results¶

Saves a speed test result to the database.

Request Body¶

{
  "testMode": "tcp",
  "downloadMbps": 560.5,
  "uploadMbps": 110.2,
  "latencyUnloadedMs": 5.3,
  "latencyLoadedMs": 17.8,
  "serverLocation": "SJC"
}

Fields¶

Field	Type	Required	Description
`testMode`	string	Yes	Test protocol: `"tcp"` or `"webtransport"`
`downloadMbps`	number	Yes	Download speed in Mbps
`uploadMbps`	number	Yes	Upload speed in Mbps
`latencyUnloadedMs`	number	Yes	Latency without load (ms)
`latencyLoadedMs`	number	Yes	Latency under load (ms)
`serverLocation`	string	No	Cloudflare edge location code

Response¶

{
  "success": true
}

Example¶

curl -X POST https://ods-api.m-8b1.workers.dev/speedtest/results \
  -H "Content-Type: application/json" \
  -d '{
    "testMode": "tcp",
    "downloadMbps": 560.5,
    "uploadMbps": 110.2,
    "latencyUnloadedMs": 5.3,
    "latencyLoadedMs": 17.8
  }'

GET /speedtest/history¶

Returns the authenticated user's speed test history.

Authentication Required

This endpoint requires authentication via session cookie or API key.

Query Parameters¶

Parameter	Type	Default	Description
`limit`	number	20	Maximum results to return (max 100)

Response¶

{
  "results": [
    {
      "id": 1,
      "user_id": "user_abc123",
      "test_mode": "tcp",
      "download_mbps": 560.5,
      "upload_mbps": 110.2,
      "latency_unloaded_ms": 5.3,
      "latency_loaded_ms": 17.8,
      "server_location": "SJC",
      "client_ip": "203.0.113.42",
      "client_location": "San Francisco, US",
      "client_asn": "AS7922",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2025-01-15T12:00:00Z"
    }
  ]
}

Example¶

curl https://ods-api.m-8b1.workers.dev/speedtest/history?limit=10 \
  -H "Cookie: session=..."

Understanding Latency Metrics¶

Unloaded Latency¶

Latency measured when the network is idle. This represents the minimum round-trip time to the server.

Loaded Latency¶

Latency measured during active downloads. A significant difference between unloaded and loaded latency indicates bufferbloat, which causes lag and poor responsiveness during heavy network usage.

Latency Difference	Quality
< 10ms	Excellent
10-50ms	Good
50-100ms	Fair
> 100ms	Poor (bufferbloat)

Test Modes¶

The speed test supports two modes:

Standard Mode (TCP)¶

Duration: ~25 seconds total
Download chunks: 10MB per request
Upload chunks: 2MB per request
Parallelism: 4 concurrent connections
Latency pings: 10 samples

Best for: Maximum accuracy on high-bandwidth connections.

Fast Mode (HTTP/3)¶

Duration: ~12 seconds total
Download chunks: 5MB per request
Upload chunks: 1MB per request
Parallelism: 6 concurrent connections
Latency pings: 5 samples
Server optimizations: Smaller chunks (16KB), reused data buffers

Best for: Quick checks, mobile networks, or when you need faster results.

HTTP/3 and QUIC

Fast mode leverages HTTP/3, which runs over QUIC (a UDP-based protocol). This provides:

Faster connection establishment (0-RTT)
Better performance on lossy networks
Multiplexed streams without head-of-line blocking

Cloudflare's edge network automatically negotiates HTTP/3 when supported by the client.

Test Methodology¶

The speed test uses the following methodology:

Unloaded Latency - Ping samples (10 standard, 5 fast), median RTT
Download Speed - Parallel streams for duration (10s standard, 5s fast)
Loaded Latency - Pings during active download
Upload Speed - Parallel streams for duration (10s standard, 5s fast)

Cloudflare Edge Network¶

Tests are served from Cloudflare's global edge network, ensuring low-latency connections from most locations worldwide. The server.location field indicates the 3-letter airport code of the serving edge location (e.g., SJC = San Jose, LAX = Los Angeles).