hey HTTP Load Generator: Quick API Benchmarking with Go

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/releases

Verify:

hey --version
# hey, version 0.1.4

Running Your First Load Test

The minimal hey command:

hey -n 1000 -c 50 https://api.example.com/health

Flags:

  • -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 responses

The 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/api

For 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/users

Multiple -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/users

For 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/api

To 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 differently

Disabling 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/api

This 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/api

hey 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.csv

Each 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/api

The -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/api

Or 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 100 means 50 workers, each targeting 2 RPS. Total: 100 RPS.
  • -c 10 -q 100 means 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.sh

Comparing 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.txt

Common 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.

Read more

Start now free