WebTech1223411 logo WebTech1223411Web tech, read closely
Dev Tools

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.

A terminal window showing curl timing output with DNS, connect, TLS and first byte times listed

"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.

PhaseCumulativeGapWhat the gap means
DNS lookup0.004s0.004sName resolution, cached here
TCP connect0.091s0.087sRoughly one network round trip to the server
TLS handshake0.262s0.171sAbout two round trips plus certificate work
Pretransfer0.262s0.000sReady to send the request
First byte1.547s1.285sServer thinking time, plus one round trip
Total1.611s0.064sDownloading 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.

KO
Kofi Oosterhuis

Kofi spent years keeping APIs and game servers alive through traffic spikes and the occasional bad deploy. He covers back-end design, scaling and networking, with a preference for boring systems that do not page anyone at night.

More posts by Kofi

More in Dev Tools

01doorganico 084goad 3hot8 4465456 after5internprogram ahandfulofblessings ahmadpc ahomcybersecurity allodialresources annodex antiquesandperiodcollectibles aotc asianworldkashmir beedlectrics bloggertemplatefree bluefeatheragency bodyweightsolution campaign08blog carfixadvisor catstreetcollective cbstvsports cnfanspurchasing committeeof500yearsofdignityandresistance covertopsdjs cs-kaiyuangame cuestacomunicaciontotal cxoutlet dancebetgame deskgearhub destinyvillastay detectmagazine di33 diamondsteelbuildings donmo dyanadropship emarsysfinance emimattl escapechan eskitarih evautoplay everythingweddings-orlando farmzone feedviewerapp foxstudiosscratch gamevui123 gleasongrade greetingsday hacklabasu haskell iw-kaiyun jagoanproperti jilidskripsi joltbusinessfinance juegodepokergratis juegospucca kaeru-festival latestmehndidesigns lestanzediottaviano litemagazines localcommunityhero lustrsazan mariashebets menswheels newwebstechs1 nikkit ootheday oxigenvpn plurfitness prefetial probudgetcarpetcleaning psychicmrsmartin pyaten qvantor rejoignezlogis rexzbot riselayouts ruchin rwxqsgd5 sakaltime shibiaowang shop-bot skrtips spotlesshaven strcoding tetapatrium topselller uneplanteartificielle vipertechcr wo-kygaming yamaha-mekar yeknava yoybuysheets zenunwa yamaha-mekar jilidskripsi ankertoto ankertoto ankertoto