Event-scoped custom dimensions and metrics reporting


You need Edit permission to create and edit event-scoped custom dimensions and metrics.

Event-scoped custom dimensions and metrics take their values from the event parameters you collect via the Analytics measurement code. Automatically collected events have some default parameters, and you can specify up to 25 custom parameters per event (Android or iOS).

During the creation process, you identify the event parameter that will supply the value for the custom dimension or metric.

When you collect that parameter with an event, the corresponding custom dimension or metric will be displayed on a data card in the event-detail report.

You can create 50 custom dimensions and 50 custom metrics per property.

The ability to create up to 100 custom dimensions and metrics is available with Google Analytics 4 properties. If you're using Google Analytics for Firebase, you need to upgrade to a Google Analytics 4 property.

If you are not using a Google Analytics 4 property, then you can identify up to 50 custom dimensions and metrics per project (40 custom dimensions and 10 custom metrics).

This feature replaces custom-parameter reporting. With custom-parameter reporting, parameters were identified for individual events. Consequently, if you wanted to report on the same parameter for five different events, you had to use five of your 100 limit. With event-scoped custom dimensions and metrics, parameters are identified for property-wide dimensions and metrics, so you can create a single dimension or metric based on a parameter and report on it for as many events as you like.

With the deprecation of custom-parameter reporting, Analytics has preserved historical event-scoped aggregates, and new aggregates seamlessly extend that historical data. In cases where a parameter was registered for multiple events, Analytics disambiguates between them by assigning a dimension/metric name that includes the currently assigned event name (e.g., “custom_dimension_name [event_name]”). As a best practice, you should remove duplicate custom dimensions and metrics that were registered across multiple events to help preserve quota.

Create and edit event-scoped custom dimensions and metrics


  1. Sign in to Google Analytics.
  2. In the left pane, click All events.
  3. Click Manage Custom Definitions.
  4. To create a custom dimension, click the Custom dimensions tab > Create custom dimensions.

    To create a custom metric, click the Custom metrics tab > Create custom metrics.
  5. In the Event parameter name field, enter the name of the parameter that will provide the value for the custom dimension or metric. You can choose from a list of existing parameters that are being collected or enter a new name for a parameter you plan to collect in the future.
  6. (Custom metrics only) In the Unit of measurement field, select the appropriate unit of measurement for the custom metric.
  7. In the Custom dimension name or Custom metric name field, enter a unique name. This is the name that will be displayed throughout reports so use a descriptive name.
  8. Click Save.


  1. In the left pane, click All events.
  2. In the row for the dimension or metric, click and then, then click Edit.
  3. Make the changes you want, then click Save.


The per-property count for custom dimensions and metrics appears at the bottom of the list, and increments as you create new ones. When you reach the quota of 100, that number appears in red, indicating that you cannot create any more.

When you create custom dimensions and metrics, a data card for each one is added to the related event-detail report. However, it may take up to 24 hours for the data to appear. During this 24-hour period, you may see (not set) appear as a custom dimension or metric value. Once that initial 24-hour period has passed, you will see the expected values from that point forward.

Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue