What is the Web Performance API?

What is the Web Performance API?

The Web Performance API, usually called the Performance API, is a set of browser standards for measuring how a web page performs. It records timings for navigation, resources, paint and long tasks on a high-precision timeline, lets you add your own marks and measures, and works in pages and in workers, so you can send real-user numbers to your analytics.

How it works

Every metric is a PerformanceEntry with a name, a startTime, a duration and an entryType. The browser records most entries automatically. You can read them with performance.getEntries(), but the better way is a PerformanceObserver, which notifies you as new entries are recorded. The same data is also what feeds the Performance Timeline shown in browser developer tools.

The entry types you will use most

• Navigation timing: one entry for the current document, with redirectCount, domInteractive, domComplete, loadEventEnd and a type of navigate, reload or back_forward.
• Resource timing: network timing for every image, script, stylesheet and fetch call, including initiatorType, transferSize, responseStatus and nextHopProtocol.
• Paint, LCP and layout shift: paint timing, Largest Contentful Paint and layout shift entries, the raw material for Core Web Vitals.
• Event timing and long tasks: event latency (the basis of Interaction to Next Paint) and tasks that block the main thread.
• Marks and measures: your own markers and the time between them, useful for steps such as "checkout started" to "checkout rendered".

Example

This snippet logs every resource as it loads, reads the navigation entry and times a custom step:

const po = new PerformanceObserver((list) => {
  for (const e of list.getEntries()) console.log(e.name, e.duration);
});
po.observe({ type: "resource", buffered: true });

const [nav] = performance.getEntriesByType("navigation");
console.log(nav.type, nav.domInteractive, nav.loadEventEnd);

performance.mark("checkout-start");
// ... work ...
performance.mark("checkout-end");
performance.measure("checkout", "checkout-start", "checkout-end");

Note that buffered: true works with type (one entry type per call), not with entryTypes. It also delivers entries recorded before you called observe().

Common mistakes

• Reading cross-origin timings and getting zeros. For resources from another origin, fields such as domainLookupStart, connectStart and requestStart return 0 unless that server sends a Timing-Allow-Origin header.
• Mixing entryTypes with buffered. Use type when you need buffered entries, one observer per type.
• Observing too late. Observers registered after the page has loaded miss earlier entries unless you ask for buffered ones.
• Trusting one visit. The API measures a single user on a single device and network. Aggregate many visits and look at percentiles, not one number.
• Assuming a value of 0 for transferSize is an error. It indicates a local cache hit.

Performance API, real user monitoring and synthetic tests

The Performance API is how real user monitoring gets its data: it runs in your visitors' browsers and shows what they actually experienced. Synthetic monitoring does the opposite: a scripted test loads the page on a schedule from a known location, so results are comparable run to run. You want both. LoadFocus page speed monitoring runs scheduled Lighthouse audits from cloud regions and keeps the history, and the free Core Web Vitals checker gives a quick reading for any URL. For a step-by-step setup see our guide to monitoring Core Web Vitals with alerts and reports. The API is also available inside a web worker, so heavy work off the main thread can be timed too.

FAQ

What is the difference between the Performance API and the Performance Timeline?

The Performance API is the set of interfaces and methods you call from JavaScript. The performance timeline is the ordered record of entries the browser keeps, which the API reads and which developer tools display.

Should I use getEntries() or PerformanceObserver?

Prefer PerformanceObserver. It is notified as entries are recorded, so you do not have to poll, and with the type option and buffered set to true it also returns entries recorded earlier.

Why are some timing values 0 for third-party resources?

For cross-origin resources the browser hides detailed timings such as DNS lookup and connection start. The server that hosts the resource has to send a Timing-Allow-Origin header to expose them.

Does the Performance API replace a monitoring tool?

No. It collects measurements in the browser, but you still need somewhere to store, aggregate and alert on them. Pair it with scheduled synthetic checks so you also notice problems when nobody is visiting.