How to capture response metrics with cURL write-out

When a curl request is used in shell automation, API debugging, or health checks, the response body alone does not explain whether the request was fast, redirected, or even reached the expected endpoint. Capturing response metrics makes it easier to prove success, compare runs, and spot regressions without turning every request into a full verbose trace.

The --write-out option expands selected variables after the transfer finishes, so one command can return both the payload and a small metrics summary. Current upstream curl documentation uses {response_code} as the canonical HTTP status variable, while older examples often show the legacy alias {http_code}. When downstream tooling needs a broader machine-readable snapshot, curl can also emit a full {json} object of transfer metadata.

Write-out values are client-side observations, so numbers such as {time_total} and fields such as {remote_ip} can change between runs as DNS answers, connection reuse, proxies, redirects, and network conditions change. When the response body is not needed, discard it with --output /dev/null; when it is needed, save it to a file so the metrics block stays parseable. The newer output{...} write-out destination requires curl 8.3.0 or newer, so older builds should keep using normal shell redirection for log files. The examples below use masked health-check and release-manifest URLs plus documentation-only transfer values so the workflow stays realistic without publishing a live endpoint or network address.

1. Print a compact metrics summary for one request while discarding the response body.

   $ curl --silent --show-error --output /dev/null --write-out "response_code=%{response_code}\nurl=%{url_effective}\ntime_total=%{time_total}\nsize_download=%{size_download}\n" https://api.example.net/health
   response_code=200
   url=https://api.example.net/health
   time_total=0.184672
   size_download=428

   {response_code} is the current variable name in the upstream manual. Older curl examples that use {http_code} still refer to the same HTTP status value.

2. Save a reusable write-out format file when the same metrics need to be collected repeatedly.

   $ cat > curl-metrics-format.txt <<'EOF'
   response_code=%{response_code}
   remote_ip=%{remote_ip}
   remote_port=%{remote_port}
   scheme=%{scheme}
   time_starttransfer=%{time_starttransfer}
   time_total=%{time_total}
   size_download=%{size_download}
   EOF

   Putting the format string in a file avoids repeated shell quoting and keeps scripted requests consistent across runs.

3. Reuse the format file and save the response body separately so the metrics stay clean.

   $ curl --silent --show-error --output api-health-response.json --write-out @curl-metrics-format.txt https://api.example.net/health
   response_code=200
   remote_ip=192.0.2.24
   remote_port=443
   scheme=HTTPS
   time_starttransfer=0.176548
   time_total=0.176904
   size_download=428

   Using --output api-health-response.json keeps the response body out of standard output, so the write-out block stays easy to copy, diff, or parse.

4. Append a metrics block straight to a log file with the write-out output{...} destination.

   $ curl --silent --show-error --output /dev/null --write-out '%output{>>api-health-metrics.log}response_code=%{response_code}\nurl=%{url_effective}\ntime_total=%{time_total}\nsize_download=%{size_download}\n' https://api.example.net/health
   $ tail -n 4 api-health-metrics.log
   response_code=200
   url=https://api.example.net/health
   time_total=0.181227
   size_download=428

   output{>>api-health-metrics.log} appends directly from curl without mixing the response body into the log. If your curl build is older than 8.3.0, redirect standard output to the log file instead.

5. Show metrics only when a request fails so successful runs stay quiet but error details are still captured.

   $ curl --silent --show-error --fail --output /dev/null --write-out '%{onerror}response_code=%{response_code}\nexitcode=%{exitcode}\nerrormsg=%{errormsg}\n' https://api.example.net/v1/releases/rel-2026-03-29/manifest
   curl: (22) The requested URL returned error: 404
   response_code=404
   exitcode=22
   errormsg=The requested URL returned error: 404

   {onerror} only prints when curl returns a non-zero exit. Pair it with --fail or --fail-with-body when HTTP 4xx or 5xx responses must count as failures instead of successful transfers.