hey HTTP Benchmarking

hey cheatsheet — HTTP load testing with -n requests and -c concurrency. hey -n 10000 -c 200 https://api.example.com. GET, POST, custom headers and body supported.

5 min read

What it is

hey is a tiny, fast, and simple HTTP benchmarking tool written in Go, perfect for quickly measuring the performance of your web services under load.

Installation

Linux

sudo apt update && sudo apt install hey
# or
sudo yum install hey
# or download from releases and place in your PATH

Mac

brew install hey

Windows

Download the pre-compiled binary from the hey releases page and add it to your system’s PATH.

Commands / Usage

Basic Benchmarking

Benchmark a single URL

hey https://example.com

Sends 50 requests to https://example.com with a concurrency of 10.

Specify the number of requests

hey -n 1000 https://example.com

Sends 1000 requests to https://example.com.

Specify the concurrency level

hey -c 50 https://example.com

Sends requests to https://example.com with 50 concurrent connections.

Specify both requests and concurrency

hey -n 5000 -c 100 https://example.com

Sends 5000 requests to https://example.com with 100 concurrent connections.

Benchmark multiple URLs simultaneously

hey -n 100 https://example.com https://api.example.com/v1/users

Sends 100 requests, distributed across https://example.com and https://api.example.com/v1/users.

Benchmark a URL with a specific HTTP method

hey -m POST https://api.example.com/submit-data

Sends 50 POST requests to https://api.example.com/submit-data.

Benchmark a URL with custom headers

hey -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_TOKEN_HERE" https://api.example.com/resource

Sends 50 requests to https://api.example.com/resource with specified headers.

Benchmark a URL with a request body

hey -m POST -D request_body.json https://api.example.com/create

Sends 50 POST requests to https://api.example.com/create with the content of request_body.json as the request body.

Benchmark a URL with a timeout

hey -t 30s https://example.com

Sets a total timeout of 30 seconds for the entire benchmark.

Benchmark a URL with a connection timeout

hey -T 5s https://example.com

Sets a connection timeout of 5 seconds for establishing each connection.

Output Control

Disable the progress bar

hey -p off https://example.com

Runs the benchmark without displaying the progress bar.

Disable the histogram output

hey -H off https://example.com

Runs the benchmark without displaying the response time histogram.

Output results in JSON format

hey -o json https://example.com

Prints the benchmark results in JSON format.

Output results in Go-getter format

hey -o getter https://example.com

Prints the benchmark results in a format compatible with Go-getter (useful for scripting).

Advanced Options

Disable keep-alive connections

hey -disable-keepalive https://example.com

Forces a new connection for each request, disabling HTTP keep-alive.

Use HTTP/1.1

hey -http11 https://example.com

Forces the use of HTTP/1.1 for all requests.

Use HTTP/2

hey -http2 https://example.com

Forces the use of HTTP/2 for all requests.

Specify the rate of requests per second

hey -r 100 https://example.com

Attempts to maintain a rate of 100 requests per second.

Specify the rate and duration

hey -r 100 -d 1m https://example.com

Attempts to maintain a rate of 100 requests per second for 1 minute.

Listen on a specific local address

hey -host 127.0.0.1:8080 https://example.com

Binds the outgoing connections to 127.0.0.1:8080.

Use a specific client certificate and key

hey -cert cert.pem -key key.pem https://example.com

Uses the provided client certificate and key for mutual TLS authentication.

Disable TLS verification

hey -disable-redirects https://example.com

Disables automatic following of HTTP redirects.

Set the maximum number of redirects

hey -max-redirects 5 https://example.com

Sets the maximum number of redirects to follow (default is 10).

Run benchmark for a specific duration

hey -d 30s https://example.com

Runs the benchmark for exactly 30 seconds.

Common Patterns

High load test for a short duration

hey -n 10000 -c 200 https://api.example.com/users

Simulates a high burst of traffic to test how the API handles it.

Sustained load test for a longer period

hey -d 5m -r 500 https://example.com

Tests the server’s ability to handle a consistent load of 500 requests per second for 5 minutes.

Benchmarking API endpoints with POST data

echo '{"name": "test user"}' > data.json && hey -m POST -D data.json -n 500 -c 50 https://api.example.com/users

Creates a user via a POST request with JSON data and benchmarks the endpoint.

Testing with and without keep-alive to measure connection overhead

hey -disable-keepalive -n 1000 https://example.com
hey -n 1000 https://example.com

Compare the results of disabling keep-alive versus using it to understand connection setup costs.

Redirects test

hey -n 100 -max-redirects 20 https://example.com

Tests how the server handles a chain of redirects, up to 20.

JSON output for scripting

hey -o json https://example.com > results.json && cat results.json

Captures benchmark results in JSON format for further processing or analysis.

Gotchas

Default values: If you don’t specify -n and -c, hey defaults to 50 requests and 10 concurrent connections. This might not be enough for meaningful performance testing.
Rate limiting (-r): The rate limiting is best-effort. hey will try to maintain the specified rate, but network conditions and server response times can affect the actual throughput.
Large number of requests: Running hey with a very large number of requests (-n) and high concurrency (-c) can consume significant local resources (CPU, memory, network sockets). Be mindful of your machine’s capacity.
HTTP/2 behavior: When using HTTP/2, hey multiplexes requests over a single connection. The reported connection count in the output might be misleading if you’re expecting a new connection per request.
TLS verification: By default, hey verifies TLS certificates. If you are testing a service with a self-signed certificate or an untrusted issuer, you might need to disable verification (though this is generally not recommended for production testing). There isn’t a direct flag for this in hey, you’d typically handle this at a lower network level or by trusting the CA.
Redirects: hey follows redirects by default up to 10 levels. If your application has a very deep redirect chain, you might hit this limit. Use -max-redirects to adjust.