TIL: Measuring API Response Times With curl -w

A slow API feels slow. curl -w tells you exactly where the time goes.

curl -w "\ntime_total: %{time_total}s\ntime_connect: %{time_connect}s\ntime_starttransfer: %{time_starttransfer}s\n" \
  -X POST https://api.example.com/v1/listen \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/audio.wav"}'

The -w flag prints timing variables after the response. time_total is the full request duration. time_connect is the TCP handshake. time_starttransfer is when the first byte of the response arrives.

curl -w "@timing-format.txt" -o /dev/null -s https://api.example.com/v1/models

Put the format string in a file. The @filename syntax reads it from there. Keep it in your dotfiles for consistent measurements.

# timing-format.txt
\n
HTTP code: %{http_code}\n
DNS: %{time_namelookup}s\n
Connect: %{time_connect}s\n
TLS: %{time_appconnect}s\n
First byte: %{time_starttransfer}s\n
Total: %{time_total}s\n

Breakdown of every phase. DNS lookup, TLS handshake, and response time are measured separately.

Can I log timings to a file?

Use the -w flag combined with -o to write the response body to a file and -w to append timings to a log file.

curl -w "..." -o /dev/null -s https://api.example.com/v1/listen >> timing.log