What is the Server-Timing API?

What is the Server-Timing API?

Server-Timing is an HTTP response header that lets your server report how long its own work took, such as a database query, a cache lookup or template rendering. The browser shows these metrics in its developer tools and exposes them to JavaScript through the PerformanceServerTiming interface. It answers a question the browser cannot answer on its own: when a response is slow, where on the server did the time go?

Syntax

Each metric has a name and, optionally, a duration and a description. Several metrics are separated by commas. According to MDN:

Server-Timing: db;dur=53, cache;desc="Cache Read";dur=23.2, app;dur=47.2

• name: a token with no spaces or special characters, defined by your server.
• dur: the duration as dur= followed by a number, for example dur=23.2.
• desc: a description as a token or quoted string, for example desc="DB lookup".

In JavaScript the same fields map to name, duration and description on each PerformanceServerTiming entry. MDN recommends keeping names and descriptions short to limit header overhead.

How it works

1. Your server measures its own phases, for instance the time spent in the database and in rendering.
2. It adds them to the response in a Server-Timing header.
3. The browser lists them in the Network panel's timing view, and a script can read them from the page's performance entries.
4. A real user monitoring script can collect them for every visit and send them to your analytics.

Example

Your Time to First Byte is 900 ms on a product page. TTFB alone cannot say why. With Server-Timing: db;dur=620, render;dur=210 the answer is visible at once: most of the time is the database. The fix targets a query, not the CDN or the frontend.

Common mistakes

• Leaking internals. MDN warns that the header may expose sensitive application and infrastructure information. Decide what to send and to whom, for example only for authenticated users or staff.
• Expecting cross-origin access. The interface is restricted to the same origin. To let other origins read the metrics, the response needs a Timing-Allow-Origin header.
• Measuring too coarsely. One total metric tells you little. Split by phase: database, cache, external calls, rendering.
• Sending it everywhere in production without a plan. Extra headers add bytes to every response. Keep the set small.
• Confusing it with the browser-side timeline. Server-Timing reports what the server measured. It does not cover network time or what happens after the response arrives. For that side, see the Web Performance API.

Server-Timing, testing and monitoring

Server-Timing is most useful alongside measurements from outside. A synthetic check or a latency measurement shows that a response got slower, and the header then points at the layer responsible. LoadFocus API monitoring splits each run's response time into wait, DNS, TCP connect, first byte and download, so you can tell network from server time first and then use Server-Timing to look inside the server part. To dig further into slow endpoints, see common API performance issues and how to detect them.

FAQ: Server-Timing

Is Server-Timing supported in browsers?

MDN lists it as Baseline widely available, in browsers since March 2023, with some parts varying by browser. It is only available in secure contexts (HTTPS) in some browsers.

Can JavaScript read the Server-Timing values?

Yes, through the PerformanceServerTiming interface. Cross-origin responses also need a Timing-Allow-Origin header.

Does it measure network time?

No. It reports only what your server chooses to measure. Network and browser time come from other timings.

Is it safe to expose in production?

It can be, if you limit what you send. The header may reveal infrastructure details, so many teams send it only to authenticated or internal users.

Can the header be sent as a trailer?

Yes, but MDN notes that only the browser's DevTools can display it that way. The Fetch API cannot access HTTP trailers.