hey HTTP Load Generator: Quick API Benchmarking with Go
hey is a Go-based HTTP load generator originally named boom. It's the tool you reach for when you need a quick answer to "how fast is this endpoint" without setting up a config file or learning a new DSL. Single binary, straightforward flags, good output. That's it.
Where wrk is C-based and Lua-scriptable, hey is pure Go with a simpler interface — no scripting, but also no compilation step and cross-platform binaries that just work. It handles HTTP/1.1 and HTTP/2, supports POST bodies and custom headers, and outputs both a human-readable histogram and an optional CSV for further analysis.
Installing hey
# macOS
brew install hey
# Go install
go install github.com/rakyll/hey@latest
# Download binary directly from GitHub releases
# https://github.com/rakyll/hey/releasesVerify:
hey --version
# hey, version 0.1.4Running Your First Load Test
The minimal hey command:
hey -n 1000 -c 50 https://api.example.com/healthFlags:
-n 1000— total number of requests (default: 200)-c 50— concurrent workers (default: 50)
Output:
Summary:
Total: 4.3212 secs
Slowest: 0.2341 secs
Fastest: 0.0089 secs
Average: 0.0211 secs
Requests/sec: 231.42
Total data: 145000 bytes
Size/request: 145 bytes
Response time histogram:
0.009 [1] |
0.031 [856] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
0.053 [89] |■■■■■■
0.075 [32] |■■
0.097 [14] |■
0.119 [5] |
0.142 [2] |
0.164 [1] |
0.186 [0] |
0.209 [0] |
0.234 [0] |
Latency distribution:
10% in 0.0120 secs
25% in 0.0145 secs
50% in 0.0189 secs
75% in 0.0234 secs
90% in 0.0312 secs
95% in 0.0412 secs
99% in 0.0967 secs
Details (average, fastest, slowest):
DNS+dialup: 0.0001 secs, 0.0089 secs, 0.2341 secs
DNS-lookup: 0.0000 secs, 0.0000 secs, 0.0021 secs
req write: 0.0000 secs, 0.0000 secs, 0.0001 secs
resp wait: 0.0210 secs, 0.0088 secs, 0.2340 secs
resp read: 0.0000 secs, 0.0000 secs, 0.0001 secs
Status code distribution:
[200] 1000 responsesThe output breaks down latency by percentile and time component. resp wait is server-side processing time. DNS+dialup includes connection overhead. The histogram shows the shape of the distribution at a glance.
Setting a Request Rate
By default hey sends requests as fast as possible. Use -q to set a rate limit in requests per second:
# 100 requests per second for 200 total requests
hey -n 200 -c 20 -q 100 https://api.example.com/apiFor sustained load testing, combine with -z (duration) instead of -n:
# 100 RPS for 30 seconds
hey -z 30s -c 100 -q 100 https://api.example.com/api-z is often more useful than -n for load testing because you control duration rather than request count. The number of requests becomes an output of the test, not an input.
Adding Headers and Auth
hey -n 500 -c 50 \
-H "Authorization: Bearer eyJhbGci..." \
-H "Content-Type: application/json" \
-H "X-Request-Source: load-test" \
https://api.example.com/api/usersMultiple -H flags stack. Hey sends them all.
POST Requests
For POST with a JSON body:
hey -n 500 -c 50 \
-m POST \
-H "Authorization: Bearer eyJhbGci..." \
-H "Content-Type: application/json" \
-d '{"name": "test", "email": "test@example.com"}' \
https://api.example.com/api/usersFor a body read from a file:
echo '{"name": "test user", "email": "test@example.com"}' > body.json
hey -n 500 -c 50 \
-m POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhbGci..." \
-D body.json \
https://api.example.com/api/users-D reads the body from a file. -d takes the body as a string. Use -D when the body is large or contains special characters that would be annoying to escape.
HTTP/2
hey uses HTTP/2 by default for HTTPS endpoints that support it. To force HTTP/1.1:
hey -n 500 -c 50 -disable-http2 https://api.example.com/apiTo see whether the server negotiated HTTP/2:
hey -n 10 -c 1 https://api.example.com/api
# Check "Details" section — HTTP/2 responses will show connection reuse differentlyDisabling Keep-Alive
By default hey reuses connections (keep-alive). To test fresh-connection overhead:
hey -n 500 -c 50 -disable-keepalive https://api.example.com/apiThis tests a different workload — useful when your service sees many short-lived connections (mobile clients, serverless functions) rather than long-lived ones.
Ignoring TLS Certificate Errors
For staging environments with self-signed certs:
hey -n 500 -c 50 -disable-redirects \
https://staging.internal.example.com/apihey doesn't have a built-in -insecure flag. The workaround is to set the GODEBUG=tlsrsa=1 env var or configure a custom transport — or, more practically, just add your staging CA to the system trust store.
CSV Output for Analysis
hey can output per-request data as CSV:
hey -n 1000 -c 50 -o csv https://api.example.com/api > results.csvEach row contains: response-time,DNS+dialup-time,DNS-lookup-time,Request-write-time,Response-delay-time,Response-read-time,status-code,offset.
Process it with any spreadsheet or script:
# Find the 99th percentile manually
cat results.csv | awk -F',' '{print $1}' | sort -n | \
awk 'BEGIN{c=0} {a[c++]=$1} END{print a[int(c*0.99)]}'Or in Python:
import csv
import statistics
with open('results.csv') as f:
reader = csv.reader(f)
times = [float(row[0]) for row in reader]
times.sort()
p50 = times[int(len(times) * 0.5)]
p99 = times[int(len(times) * 0.99)]
print(f"P50: {p50*1000:.1f}ms")
print(f"P99: {p99*1000:.1f}ms")Setting a Host Header
For testing behind a load balancer or testing virtual hosts:
hey -n 500 -c 50 \
-host api.example.com \
http://10.0.1.5:8080/apiThe -host flag overrides the Host header without changing the actual connection target. Useful for testing a specific backend server without going through DNS.
Proxy Support
Test through an HTTP proxy:
hey -n 500 -c 50 \
-x http://proxy.example.com:8080 \
https://api.example.com/apiOr set the HTTP_PROXY / HTTPS_PROXY environment variables, which hey respects via Go's standard http.ProxyFromEnvironment.
Concurrency and Rate Together
The relationship between -c (concurrency) and -q (rate) matters:
-c 50 -q 100means 50 workers, each targeting 2 RPS. Total: 100 RPS.-c 10 -q 100means 10 workers, each targeting 10 RPS. Total: 100 RPS.
If you set a rate limit with -q, hey distributes it evenly across workers. The rate limit is a ceiling — if the server responds slowly, hey won't exceed -q but may fall below it. If you don't set -q, hey sends as fast as workers can.
For accurate constant-rate testing (important for measuring latency under realistic load), always set both -c and -q. Without -q, hey is a flood test, not a throughput measurement.
Scripted Load Test
For repeatable testing in CI or development:
#!/bin/bash
# load-test.sh
API_URL="${API_URL:-https://api.example.com}"
TOKEN="${TOKEN:-}"
RATE="${RATE:-100}"
DURATION="${DURATION:-30s}"
CONCURRENCY="${CONCURRENCY:-100}"
if [ -z "$TOKEN" ]; then
echo "ERROR: TOKEN is required"
exit 1
fi
echo "Testing $API_URL at ${RATE} RPS for $DURATION..."
RESULT=$(hey \
-z "$DURATION" \
-c "$CONCURRENCY" \
-q "$RATE" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json" \
"$API_URL/api/health")
echo "$RESULT"
# Extract P99 for threshold check
P99=$(echo "$RESULT" | grep "99% in" | awk '{print $3}')
P99_MS=$(echo "$P99 * 1000" | bc)
echo ""
echo "P99: ${P99_MS}ms"
if (( $(echo "$P99_MS > 200" | bc -l) )); then
echo "FAIL: P99 ${P99_MS}ms exceeds 200ms threshold"
exit 1
fi
echo "PASS"In GitHub Actions:
jobs:
load-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install hey
run: go install github.com/rakyll/hey@latest
- name: Run load test
env:
API_URL: https://staging.api.example.com
TOKEN: ${{ secrets.STAGING_TOKEN }}
RATE: "100"
DURATION: "30s"
run: chmod +x ./load-test.sh && ./load-test.shComparing Before and After a Deploy
hey is useful for quick before/after comparisons:
# Baseline (before deploy)
hey -n 1000 -c 100 \
-H "Authorization: Bearer $TOKEN" \
https://api.example.com/api/search?q=test > before.txt
# After deploy
hey -n 1000 -c 100 \
-H "Authorization: Bearer $TOKEN" \
https://api.example.com/api/search?q=test > after.txt
echo "=== BEFORE ==="
grep -E "Requests/sec|99%" before.txt
echo "=== AFTER ==="
grep -E "Requests/sec|99%" after.txtCommon Mistakes
Not setting -q: Without a rate limit, hey sends requests as fast as possible, which floods the server and doesn't reflect realistic traffic patterns. Always set -q unless you're specifically looking for the maximum sustainable rate.
Using -n instead of -z for load testing: Total request count makes sense for quick checks but not for sustained load tests. Use -z for duration-based tests.
Not checking the status code distribution: hey prints status codes at the bottom. If you see [429] 200 responses in a 1000-request test, your rate limiter is kicking in and the latency numbers are meaningless.
Testing over the public internet: Network latency and jitter add noise. Test from within the same region or VPC as your service for measurements that reflect server performance, not network performance.
Ignoring the histogram shape: A low average with a long tail on the right side of the histogram means slow outlier requests. Don't just look at mean and P99 — look at the shape to understand whether outliers are rare or forming a second mode.
hey vs. Other Tools
hey's strengths: zero config, instant results, good latency percentiles, CSV export for analysis. It's the tool for quick checks and CI gates.
Its limitations: no multi-endpoint scenarios, no scripting, no distributed execution, no ramp-up phases. For any of those, use k6, Artillery, or Gatling.
Use hey alongside wrk — they have similar use cases but different output formats. hey's percentile output is cleaner; wrk's throughput measurement is sometimes more accurate at very high request rates due to the C implementation's lower overhead.
For regular API endpoint health checks during development — "did this refactor make the endpoint slower?" — hey is the fastest answer to reach for.