Skip to content

Quick Start

This guide will walk you through the basic usage of httptap.

Basic Request

Run a simple HTTP request and display a rich waterfall view:

httptap https://httpbin.io

This will output a detailed timing breakdown showing:

  • DNS resolution time
  • TCP connection establishment
  • TLS handshake (for HTTPS)
  • Time to first byte (TTFB)
  • Response body transfer time

Making POST Requests

Send JSON data to an API:

httptap --data '{"name": "John Doe", "email": "john@example.com"}' https://httpbin.io/post

Auto-POST behavior

When --data is provided without --method, httptap automatically switches to POST (similar to curl).

Curl-compatible flags

The most common curl flags work unchanged. Use -X/--request for the HTTP method, -L/--location to follow redirects, -m/--max-time for timeouts, -k/--insecure to disable certificate verification, -x for proxies, and --http1.1 to force HTTP/1.1 (equivalent to --no-http2). Not every curl option is supported, so stick to these shared flags when swapping commands.

Load data from a file:

echo '{"title": "New Post", "content": "Hello World"}' > post-data.json
httptap --data @post-data.json https://httpbin.io/post

Using Other HTTP Methods

httptap supports all standard HTTP methods:

PUT request: 

httptap --method PUT --data '{"status": "updated"}' https://httpbin.io/put

PATCH request: 

httptap --method PATCH --data '{"field": "value"}' https://httpbin.io/patch

DELETE request: 

httptap --method DELETE https://httpbin.io/delete

HEAD request (headers only): 

httptap --method HEAD https://httpbin.io/get

Adding Custom Headers

Add custom HTTP headers using the -H flag:

httptap -H "Accept: application/json" https://httpbin.io/json

Multiple headers can be added by repeating the flag:

httptap \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://httpbin.io/bearer

Following Redirects

By default, httptap does not follow redirects. To follow redirect chains:

httptap --follow https://httpbin.io/redirect/3

This will show timing information for each step in the redirect chain.

Compact Output

For a single human-readable line per step — suitable for terminal logs and tailing through grep / tee:

httptap --compact https://httpbin.io/get

Output example:

Step 1: 200 GET https://httpbin.io/get | dns=8.9ms connect=97.0ms tls=194.6ms ttfb=446.0ms total=447.3ms | 389 B

The line leads with the HTTP status so failures stand out; timings carry the ms suffix and the response size is rendered with an appropriate unit (B, KB, MB). Redirect chains still end with the full Redirect Chain Summary table so the overall shape of the request stays visible.

For machine-parseable key=value output (no units, IP/family/TLS fields included), use --metrics-only below.

Metrics-Only Mode

Get raw metrics without formatting, perfect for scripts:

httptap --metrics-only https://httpbin.io

Output example:

Step 1: dns=30.1 connect=97.3 tls=199.0 ttfb=472.2 total=476.0 status=200 bytes=389 ip=44.211.11.205 family=IPv4 tls_version=TLSv1.2 proxy=direct

JSON Export

Export full request data to JSON for later analysis:

httptap --json output.json https://httpbin.io

The JSON file will contain:

  • Detailed timing for all phases
  • Network information (IP, TLS version, certificate details)
  • Response metadata (status, headers, body size)
  • Full redirect chain (if --follow is used)
  • SLO evaluation (if --slo is supplied)

SLO Threshold Checking

Gate CI jobs, cron probes, or Kubernetes readiness checks on per-phase latency budgets with --slo:

httptap --slo total=500,ttfb=200 https://httpbin.io/get

Exit code is 0 when every budget passes and 4 when any threshold is violated. The full waterfall is still rendered so you can see why the check failed.

Supported SLO keys

dns, connect, tls, ttfb, wait, xfer, total — each maps to a timing phase. See the dedicated SLO Threshold Checking page for the full specification and recipes.

Common Use Cases

API Testing

Test a complete REST API workflow:

# Create a resource
httptap --data '{"title": "Test Post"}' https://httpbin.io/post

# Update the resource
httptap --method PUT --data '{"title": "Updated Post"}' https://httpbin.io/put

# Partial update
httptap --method PATCH --data '{"published": true}' https://httpbin.io/patch

# Delete the resource
httptap --method DELETE https://httpbin.io/delete

Check API Latency

httptap --compact https://httpbin.io/status/200

Debug Slow Responses

httptap https://httpbin.io/delay/3

The waterfall view will help identify which phase is causing the delay (DNS, connection, TLS, or server processing).

Verify TLS Configuration

httptap https://httpbin.io

Check the TLS version, cipher suite, and certificate expiration in the output.

Performance Benchmarking

Establish performance baselines and track changes over time:

# Collect 10 samples and calculate statistics
for i in {1..10}; do
  httptap --metrics-only https://httpbin.io/delay/1
done | awk '/total=/ {
  # Extract total value
  for (i = 1; i <= NF; i++) {
    if ($i ~ /^total=/) {
      sub(/^total=/, "", $i)
      sum += $i
      values[++count] = $i
      break
    }
  }
}
END {
  if (count > 0) {
    avg = sum / count
    printf "Average: %.1f ms\n", avg
    printf "Samples: %d\n", count

    # Calculate min/max
    min = values[1]; max = values[1]
    for (i = 1; i <= count; i++) {
      if (values[i] < min) min = values[i]
      if (values[i] > max) max = values[i]
    }
    printf "Min: %.1f ms\n", min
    printf "Max: %.1f ms\n", max
    printf "Range: %.1f ms\n", (max - min)
  }
}'

Example output: 

Average: 1490.0 ms
Samples: 10
Min: 1445.4 ms
Max: 1532.4 ms
Range: 87.0 ms

This helps identify performance variability and establish reliable baselines for regression testing.

What's Next?