How to Use the User Timing API: Complete Guide (2026)

Why Custom Timing Matters Beyond Core Web Vitals

Core Web Vitals capture page-level user experience: LCP for largest paint, CLS for layout stability, INP for input responsiveness. They’re excellent at flagging that a page feels slow, but they don’t tell you why a specific feature is slow.

If your “Add to Cart” click takes 800 ms to render, no Core Web Vital will localize the cause. INP will report a high latency for that interaction class, but it can’t tell you whether the cost is in your event handler, your fetch call, your render, or your post-render commit. The User Timing API fills that gap by letting you mark each phase explicitly.

• Application-level visibility: measure exactly the code paths you care about — search, checkout, route transitions, chart rendering.
• Real-user data, not synthetic: marks fire in the user’s actual browser, capturing real-world device, network, and CPU conditions.
• Cross-tool integration: marks appear in DevTools and stream to PerformanceObserver, so the same instrumentation works for local profiling and production RUM.
• INP root-cause analysis: bracket your event handler with marks to break a high INP into “handler ran for X ms, render took Y ms.”

How performance.mark and performance.measure Work

The API is two methods deep. Everything else builds on these.

// 1. Drop a named timestamp
performance.mark('search-start');

// ...do work...
runSearch(query);

// 2. Drop another timestamp
performance.mark('search-end');

// 3. Measure the span between the two marks
performance.measure('search', 'search-start', 'search-end');

// 4. Read the result
const [entry] = performance.getEntriesByName('search', 'measure');
console.log(`search took ${entry.duration.toFixed(1)}ms`);
// -> "search took 142.7ms"

Each mark records a high-resolution timestamp keyed by name. Each measure stores a PerformanceMeasure entry with startTime, duration, and the name you gave it. Both live on the browser’s performance timeline alongside built-in entries like navigation and largest-contentful-paint.

performance.measure('search', {
  start: startTime,        // number, ms since timeOrigin
  end: endTime,
  detail: { query, resultCount }   // arbitrary metadata
});

How to Inspect User Timings

The same marks and measures show up in three places, depending on what you’re doing:

• Greadme deep scan — surfaces unusually long custom timings on audited pages and ties them back to the affected scripts, with a one-click GitHub PR to fix the slow path.
• Greadme crawler scan — runs the same instrumentation across every indexable page, so you can spot which templates have regressed without manual profiling.
• Greadme AI visibility analyzer — confirms that the pages where you’ve fixed slow custom timings are the ones AI search engines are actually citing.
• Chrome DevTools → Performance → Timings lane — every mark and measure is rendered as a labeled bar in the “Timings” track during a profile recording, with no extra configuration.
• web.dev / PerformanceObserver — subscribe to { entryTypes: ['mark', 'measure'] } at runtime to stream entries to your RUM or analytics provider as they happen.

7 Practical Patterns for the User Timing API

performance.mark('render-chart-start');
renderChart(data);
performance.mark('render-chart-end');
performance.measure('render-chart', 'render-chart-start', 'render-chart-end');

performance.mark('search-start');
const results = await fetch('/api/search?q=' + q).then(r => r.json());
performance.mark('search-end');
performance.measure('search', 'search-start', 'search-end');

button.addEventListener('click', (e) => {
  performance.mark('add-to-cart-handler-start');
  addToCart(productId);
  performance.mark('add-to-cart-handler-end');
  performance.measure('add-to-cart-handler',
    'add-to-cart-handler-start',
    'add-to-cart-handler-end');

  requestAnimationFrame(() => {
    requestAnimationFrame(() => {
      performance.mark('add-to-cart-painted');
      performance.measure('add-to-cart-total',
        'add-to-cart-handler-start',
        'add-to-cart-painted');
    });
  });
});

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    navigator.sendBeacon('/rum', JSON.stringify({
      name: entry.name,
      duration: entry.duration,
      startTime: entry.startTime,
      detail: entry.detail ?? null,
    }));
  }
});
observer.observe({ entryTypes: ['measure'] });

performance.measure('search', {
  start: startTime,
  end: performance.now(),
  detail: { query, resultCount: results.length, route: '/products' }
});

performance.clearMarks('search-start');
performance.clearMarks('search-end');
performance.clearMeasures('search');

export function timed<T>(name: string, fn: () => T): T {
  const start = `${name}:start`;
  const end = `${name}:end`;
  performance.mark(start);
  try {
    return fn();
  } finally {
    performance.mark(end);
    performance.measure(name, start, end);
    performance.clearMarks(start);
    performance.clearMarks(end);
  }
}

// Usage:
const results = timed('search', () => runSearch(q));

Common User Timing Mistakes

User Timing API vs. Other Performance APIs

The User Timing API is one of several entry types on the browser’s performance timeline. Each answers a different question.

FAQ

What is the difference between performance.mark and performance.measure?

performance.mark(name) records a single high-resolution timestamp on the timeline. performance.measure(name, startMark, endMark) records a span with a duration between two marks (or two numeric times). You can have many marks and many measures over them.

Where do User Timing entries show up?

In Chrome DevTools, marks and measures appear in the “Timings” lane of the Performance tab during a recording. At runtime, they’re available via performance.getEntriesByType('mark') / 'measure' and stream to any PerformanceObserver watching those entry types.

Does the User Timing API cost anything in production?

The cost is negligible — each mark is a single high-resolution timestamp write. The only practical risk is letting marks accumulate in long-lived sessions; calling performance.clearMarks()after you’ve consumed them keeps memory bounded.

Can the User Timing API help with INP?

Yes — it’s one of the most useful tools for diagnosing high INP. Bracket your event handler with marks, mark again after the next paint, and measure both spans. That breaks an INP regression into “handler ran for X ms, render took Y ms,” which tells you where to optimize.

How do I send User Timing data to a RUM service?

Subscribe with PerformanceObserver({ entryTypes: ['measure'] }) and forward each entry to your endpoint with navigator.sendBeacon. Most production RUM clients ingest name, duration, startTime, and the optional detail object.

Why do performance audits prefer the User Timing API to hand-rolled timing code?

Because it’s standardized: the entries appear in DevTools without extra setup, observers can subscribe to them generically, and the API uses high-resolution timestamps (better than Date.now()). Audit tools flag heavy hand-rolled instrumentation because it’s harder to inspect and harder to ship to production telemetry.

Does the User Timing API affect SEO or AI search engines like ChatGPT and Perplexity?

Indirectly. The API itself isn’t a ranking signal, but it’s a key tool for diagnosing slow interactions that hurt INP, LCP, and overall page experience — all of which feed Google’s ranking signals and the “already ranks well” bias that AI engines like Google AI Overviews and Perplexity use when deciding which pages to cite. Better instrumentation leads to faster pages, which leads to more citations.