Skip to content

Guide 91 · Admin · GA4 + Tag Manager

Create a custom metric in GA4: turn a numeric event parameter into a number you can report on

Checked 11 November 2026 · Verification: figures recomputed in Python 3, shown in the downloadable file · Steps traced to Google help and developer pages, opened 11 November 2026 · 6-minute read

A custom metric turns a numeric event parameter into a number you can sum and average in reports. Create it in Custom definitions, and use a dimension instead for text values.

Expected signal

After the trace, Custom definitions lists a custom metric with the exact event parameter name, and the metric is usable in reports after 24 to 48 hours.

Download the reference: the create custom metrics reference (JSON) (399 bytes, MD5 093cad6df3a339a81503db635c7e2130). It holds the worked example from this guide with every figure recomputed. The file was built for this guide and checked the same day; it was not exported from a live property.

What you need

  • A numeric event parameter already being sent, confirmed in the Realtime report.
  • Editor access at property level.
  • The unit the number is measured in, such as percent or seconds.

The trace

  1. Confirm the parameter is numeric and is being collected. Select the event in the Event count by Event name card in the Realtime report. A text value such as a plan name belongs in a custom dimension, not a custom metric.
  2. Open Admin, then under Data display click Custom definitions, then the Custom metrics tab, then Create custom metric. You need Editor access or above at property level.
  3. Enter the metric name, for example Scroll depth. Enter the event parameter name exactly as the code sends it, for example scroll_depth. The parameter field cannot be changed after you save.
  4. Pick the unit of measurement. Google lists units including standard, currency, distance in feet, miles, meters or kilometres, and time in milliseconds or seconds. Pick the unit the code actually sends, not the unit you wish it sent.
  5. Click Save, then wait 24 to 48 hours. You can add the custom metric to any report after 24 to 48 hours from when the custom event parameter was sent and the custom metric was created.
  6. Check the worked example in the download. Five scroll depth readings of 42, 68, 91, 55 and 77 add to 333, and the average is 333 / 5 = 66.6. That average is the number the metric will show once it is usable.

Dead ends

DEAD END — A DIMENSION VALUE AS A METRIC. A text parameter registered as a metric has no meaningful sum or average. Categorical data belongs in an event-scoped custom dimension.

DEAD END — CREATING A METRIC FOR A PREDEFINED ONE. Do not create a custom parameter or metric when a predefined metric already exists. Check the predefined list first.

DEAD END — A UNIT THAT DOES NOT MATCH THE CODE. A metric sent in seconds and registered as milliseconds reads 1,000 times too large. The unit must match the code.

End state

The five readings add to 333 and average 66.6. The metric is Scroll depth, tied to scroll_depth, and usable 24 to 48 hours after the parameter was sent and the metric was created.

Sources

Checked 11 November 2026. The click paths above are the ones in Google's help and developer pages, opened 11 November 2026. No step in this guide was run inside a live Analytics property or a live Tag Manager container, because both need a Google sign-in and this site does not sign in as anyone. The figures on this page were recomputed in Python 3 and are shown in the downloadable file, which was checked the same day. Google moves menu items without warning; if a path on this page no longer matches, the linked help page is the current map.