Measure a transfer

“The API is slow” is a complaint, not a diagnosis. Slow where? DNS? The TLS handshake? The server thinking? The download itself? curl can tell you, because it timestamps every stage of a transfer and exposes those numbers through --write-out variables. They turn one transfer into useful timing evidence. Measure stages separately before deciding that a server or network is slow.

Print a timing record

Print a compact timing record:

curl --silent --output /dev/null --write-out 'dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} first=%{time_starttransfer} total=%{time_total} code=%{response_code}\n' https://example.org/

The body goes to /dev/null; only your formatted line prints:

dns=0.012 connect=0.048 tls=0.115 first=0.234 total=0.236 code=200

One thing trips everyone up: these values are cumulative from the start of the transfer, not per-stage durations. time_connect includes the DNS time before it. To get the cost of a single stage, subtract the previous value. In the sample above, TLS negotiation took roughly 0.115 minus 0.048, about 67 milliseconds.

The most diagnostic gap is usually first minus tls: the wait between sending the request and receiving the first response byte. That’s the server working. A large gap there with fast numbers before it means the network is fine and the backend is slow.

Interpret with care

Compare repeated runs. Connection reuse, DNS caching, server load, and network path can change each stage:

for i in 1 2 3 4 5; do
  curl --silent --output /dev/null --write-out 'total=%{time_total} code=%{response_code}\n' https://example.org/
done

The first run often pays for a cold DNS cache. Later runs may hit a warm resolver and look faster for reasons that have nothing to do with the server.

Add %{size_download} when byte counts matter — a “fast” response that returned 87 bytes of error JSON is not a healthy response, and the status code alone can miss that.

One request is not a benchmark. Collect enough samples and preserve the target, location, and time. Five requests from your laptop describe your laptop’s path to the server at that moment. That’s real evidence, as long as you label it as exactly that.