How to Use curl Timing to Find Why an API Request Is Slow
"The API is slow" is one of the least useful bug reports, and also one of the most common. Someone on the front-end team sees a request take 1.8 seconds in the browser, posts a screenshot, and three people start guessing.

"The API is slow" is one of the least useful bug reports, and also one of the most common. Someone on the front-end team sees a request take 1.8 seconds in the browser, posts a screenshot, and three people start guessing. The database is the usual suspect. Sometimes it is guilty. Just as often the time went somewhere else entirely, into a DNS lookup, a TLS handshake with a far-away load balancer, or a proxy holding the connection before the application even saw it.
Before I open a profiler or a query log, I run one curl command that splits a single request into its phases. It takes thirty seconds, it works from any machine with a shell, and it tells you which layer to blame. I have used it on game backends during launch week and on internal admin APIs nobody else would look at, and it has saved me from optimising the wrong thing more times than I can count.
The command and what it prints
curl can report timing for each stage of a request through its write-out option, -w, which takes a format string with named variables. Put the format in a small text file so you do not have to retype it. I keep mine at ~/curl-time.txt with these lines:
dns: %{time_namelookup}s\n connect: %{time_connect}s\n tls: %{time_appconnect}s\n pretransfer: %{time_pretransfer}s\n first byte: %{time_starttransfer}s\n total: %{time_total}s\n
Then run curl -s -o /dev/null -w @curl-time.txt "$API_URL/v1/orders". The -s hides the progress bar, -o /dev/null throws away the response body, and -w @file reads the format from your file. Add -H headers for authentication the same way you would for a normal request.
Each number is cumulative, measured in seconds from the start of the request. That trips people up the first time. If connect says 0.120 and tls says 0.310, the TLS handshake took 0.190 seconds, not 0.310. You read the gaps between lines, not the lines themselves.
Reading the gaps
Here is a real output from a request I debugged last spring, with the gaps worked out. The endpoint returned a list of a player's recent matches.
| Phase | Cumulative | Gap | What the gap means |
|---|---|---|---|
| DNS lookup | 0.004s | 0.004s | Name resolution, cached here |
| TCP connect | 0.091s | 0.087s | Roughly one network round trip to the server |
| TLS handshake | 0.262s | 0.171s | About two round trips plus certificate work |
| Pretransfer | 0.262s | 0.000s | Ready to send the request |
| First byte | 1.547s | 1.285s | Server thinking time, plus one round trip |
| Total | 1.611s | 0.064s | Downloading the response body |
The connection setup cost about a quarter of a second, which is normal for a server around 85 milliseconds away. The download was fast. Nearly all of the time sat in the gap between pretransfer and first byte, which is the time the server spent before it sent anything back. That points at the application or something it calls, and it rules out the network. In this case it turned out to be an N+1 pattern, one query for the match list and then one more per match, the exact problem described in how N+1 queries slow an API.
Other shapes point elsewhere. A big DNS gap, over 100 milliseconds on repeated runs, usually means a misconfigured resolver or a short TTL. A connect gap far larger than your ping time suggests packet loss or a crowded load balancer. A large gap after first byte means the body is big or the server streams it slowly, so look at payload size and compression before touching code.
Run it more than once
One run tells you very little. The first request often pays for a cold DNS cache, a fresh TLS session and maybe a cold application cache, and later runs will look faster. I loop it ten times in a shell, for i in $(seq 10); do curl -s -o /dev/null -w @curl-time.txt URL; done, and look at the spread.
If the time to first byte is consistent, say 1.2 to 1.3 seconds on every run, you have a steady cost in the code path, usually a slow query or an expensive computation. If it jumps between 80 milliseconds and 2 seconds, the cause is more likely contention: a connection pool that runs dry under load, a lock, or garbage collection pauses. Pool exhaustion has a recognisable look, fast most of the time with occasional waits that line up with busy periods. I covered that pattern in how connection pooling keeps an API responsive.
Why I do not start with the browser
The usual advice is to open the network panel in browser DevTools, and for front-end work that is the right place. The DevTools timing view breaks down the same phases, and our guide to reading the DevTools network waterfall walks through it. For back-end problems, though, I think the browser is a poor first tool.
A browser adds things that blur the picture. It reuses connections, so you may never see connect or TLS time at all. It queues requests when too many go to the same host. Extensions add delay. Service workers can answer from cache. And the browser sits on a laptop on home WiFi, while your servers talk to each other inside a data centre.
curl lets you move the measuring point. Run it from your laptop, then from a box in the same region as the API, then from inside the API's own container against localhost. If the request is slow from inside the container too, the problem is in the service. If it is fast inside and slow from outside, look at the load balancer, the CDN or the network path. Three runs from three places usually narrow it down faster than an hour in a tracing dashboard.
A few variables worth adding
The basic format covers most cases, but a few more variables earn a place in the file. %{http_code} catches the embarrassing case where you are timing a fast 401 or a cached 304 instead of the real response. %{size_download} shows the body size in bytes, which helps spot a response that grew from 40 KB to 4 MB after someone added a field. %{remote_ip} tells you which server actually answered, handy when DNS points to several and only one is slow. And %{time_redirect} shows time lost to redirects, which you will only see if you also pass -L to follow them.
For a habit to start this week, save the format file, add a shell alias such as ctime, and run it the next time someone says an endpoint is slow. Paste the output into the ticket. A bug report with phase timings attached gets fixed faster than one with a screenshot, in my experience by a day or more.
FAQ
What does time_starttransfer mean in curl?
It is the time from the start of the request until the first byte of the response arrived. It includes connection setup, so subtract pretransfer to get server time.
Why is time_appconnect zero?
That variable only covers TLS. On a plain HTTP request there is no handshake, so curl reports zero.
Does curl reuse connections between runs?
Not between separate commands. Each run opens a new connection, so you see full setup cost every time, unlike a browser.
Can I measure time spent in the database with curl?
Not directly. curl shows total server time. Add a Server-Timing header in your API to break that down further.
More in Dev Tools
Dev Tools
How to Use the DevTools Coverage Tab to Find Dead CSS
A stylesheet on a project I inherited was 184KB minified, one file for the whole site.
Dev Tools
Git Rebase vs Merge and How to Choose for Your Team
Your feature branch is three days old, main has moved on by 40 commits, and the pull request page says "This branch is out of...
Dev Tools
Console Methods Beyond console.log That Save Debugging Time
You add console.log to a loop, refresh, and the panel fills with 400 identical lines of "[object Object]" and "here".