Guide

Basic Usage

Core concepts and basic usage patterns

This guide covers the fundamental concepts of using burl for HTTP benchmarking.

The Basic Command

The simplest burl command takes just a URL:

burl https://api.example.com/health

This runs a benchmark with default settings:

10 concurrent connections
10 second duration
GET method
No custom headers

Concurrent Connections

The -c or --connections flag controls how many parallel requests burl makes:

# Light load - 5 connections
burl https://api.example.com -c 5

# Medium load - 50 connections
burl https://api.example.com -c 50

# Heavy load - 200 connections
burl https://api.example.com -c 200

More connections doesn't always mean better throughput. Start low and increase gradually to find your server's optimal concurrency.

Duration vs Request Count

You can limit a benchmark by time or by number of requests.

By Duration (Default)

Use -d or --duration with a human-readable duration:

# 30 seconds
burl https://api.example.com -d 30s

# 2 minutes
burl https://api.example.com -d 2m

# 1 hour
burl https://api.example.com -d 1h

By Request Count

Use -n or --requests to run a fixed number of requests:

# Exactly 1000 requests
burl https://api.example.com -n 1000

# Quick test - 100 requests
burl https://api.example.com -n 100

When both -d and -n are specified, the benchmark stops when either limit is reached first.

HTTP Methods

Use -m or --method to specify the HTTP method:

# GET (default)
burl https://api.example.com/users

# POST
burl https://api.example.com/users -m POST -b '{"name":"test"}'

# PUT
burl https://api.example.com/users/1 -m PUT -b '{"name":"updated"}'

# DELETE
burl https://api.example.com/users/1 -m DELETE

# PATCH
burl https://api.example.com/users/1 -m PATCH -b '{"status":"active"}'

Request Timeout

Set the maximum time to wait for a response with -t or --timeout:

# 5 second timeout
burl https://api.example.com -t 5s

# 1 minute timeout (for slow endpoints)
burl https://api.example.com -t 1m

The default timeout is 30 seconds.

Warmup Requests

Use -w or --warmup to send warmup requests that aren't counted in statistics:

# 10 warmup requests before measuring
burl https://api.example.com -w 10

Warmup helps:

Establish connection pools
Trigger JIT compilation on the server
Fill caches
Get more accurate measurements

Combining Options

Options can be combined freely:

burl https://api.example.com/users \
  -c 50 \
  -d 60s \
  -m POST \
  -b '{"name":"test"}' \
  -T application/json \
  -w 20 \
  -t 10s

This runs:

50 concurrent connections
For 60 seconds
POST requests with JSON body
20 warmup requests first
10 second timeout per request

Exit Codes

burl uses exit codes to indicate success or failure:

Exit Code	Meaning
`0`	All requests succeeded (2xx responses)
`1`	One or more requests failed

This is useful in CI/CD pipelines:

burl https://api.example.com -n 100 || echo "Some requests failed!"

Getting Started

Request Configuration

Configure headers, bodies, and authentication