Output Schema

JSON Schema

JSON output structure reference

Complete reference for burl's JSON output format.

Standard JSON Output

When using -f json, burl outputs the following structure:

{
  "config": {
    "url": "string",
    "method": "string",
    "connections": "number",
    "duration_ms": "number",
    "timeout_ms": "number",
    "warmup_requests": "number"
  },
  "summary": {
    "total_requests": "number",
    "successful_requests": "number",
    "failed_requests": "number",
    "requests_per_second": "number",
    "bytes_per_second": "number",
    "total_bytes": "number",
    "duration_ms": "number"
  },
  "latency_ms": {
    "min": "number",
    "max": "number",
    "mean": "number",
    "stddev": "number",
    "p50": "number",
    "p75": "number",
    "p90": "number",
    "p95": "number",
    "p99": "number",
    "p999": "number"
  },
  "status_codes": {
    "[code]": "number"
  },
  "errors": {
    "[error_type]": "number"
  }
}

Field Reference

Config Object

Field	Type	Description
`url`	string	Target URL
`method`	string	HTTP method used
`connections`	number	Concurrent connections
`duration_ms`	number	Configured duration in milliseconds
`timeout_ms`	number	Request timeout in milliseconds
`warmup_requests`	number	Number of warmup requests

Summary Object

Field	Type	Description
`total_requests`	number	Total requests sent (excluding warmup)
`successful_requests`	number	Requests with 2xx status
`failed_requests`	number	Requests that failed or got non-2xx
`requests_per_second`	number	Throughput (req/s)
`bytes_per_second`	number	Data transfer rate
`total_bytes`	number	Total bytes received
`duration_ms`	number	Actual test duration

Latency Object

All values in milliseconds.

Field	Type	Description
`min`	number	Minimum latency
`max`	number	Maximum latency
`mean`	number	Average latency
`stddev`	number	Standard deviation
`p50`	number	50th percentile (median)
`p75`	number	75th percentile
`p90`	number	90th percentile
`p95`	number	95th percentile
`p99`	number	99th percentile
`p999`	number	99.9th percentile

Status Codes Object

Map of HTTP status codes to their counts:

{
  "status_codes": {
    "200": 1234,
    "201": 56,
    "404": 2,
    "500": 1
  }
}

Errors Object

Map of error types to their counts:

{
  "errors": {
    "timeout": 5,
    "connection_refused": 2,
    "dns_error": 1
  }
}

Error Types

Error Type	Description
`timeout`	Request exceeded timeout
`connection_refused`	Server refused connection
`connection_reset`	Connection reset by peer
`dns_error`	DNS resolution failed
`tls_error`	TLS/SSL handshake failed
`other`	Other network errors

Example Output

{
  "config": {
    "url": "https://api.example.com/users",
    "method": "GET",
    "connections": 50,
    "duration_ms": 30000,
    "timeout_ms": 30000,
    "warmup_requests": 10
  },
  "summary": {
    "total_requests": 15234,
    "successful_requests": 15230,
    "failed_requests": 4,
    "requests_per_second": 507.8,
    "bytes_per_second": 1245678,
    "total_bytes": 37370340,
    "duration_ms": 30002
  },
  "latency_ms": {
    "min": 12.3,
    "max": 456.7,
    "mean": 98.2,
    "stddev": 45.6,
    "p50": 89.4,
    "p75": 112.3,
    "p90": 145.6,
    "p95": 178.9,
    "p99": 234.5,
    "p999": 398.2
  },
  "status_codes": {
    "200": 15230,
    "503": 4
  },
  "errors": {
    "timeout": 4
  }
}

Parsing Examples

jq

# Extract P99 latency
burl https://api.example.com -f json | jq '.latency_ms.p99'

# Get success rate
burl https://api.example.com -f json | jq '.summary.successful_requests / .summary.total_requests'

# Check for errors
burl https://api.example.com -f json | jq 'if .summary.failed_requests > 0 then "FAILED" else "OK" end'

JavaScript/TypeScript

import { execSync } from 'child_process';

interface BurlResult {
  summary: {
    requests_per_second: number;
    failed_requests: number;
  };
  latency_ms: {
    p99: number;
  };
}

const output = execSync('burl https://api.example.com -f json').toString();
const result: BurlResult = JSON.parse(output);

if (result.latency_ms.p99 > 200) {
  console.error('P99 latency too high!');
}

Python

import subprocess
import json

result = subprocess.run(
    ['burl', 'https://api.example.com', '-f', 'json'],
    capture_output=True,
    text=True
)
data = json.loads(result.stdout)

print(f"Requests/sec: {data['summary']['requests_per_second']}")
print(f"P99 Latency: {data['latency_ms']['p99']}ms")

Examples

LLM Output

LLM-optimized output format reference