Preferences

Privacy is important to us, so you have the option of disabling certain types of storage that may not be necessary for the basic functioning of the website. Blocking categories may impact your experience on the website. More information (Cookie Policy)

Google Analytics Dimensions: What They Are and How to Use Them in GA4

What Google Analytics dimensions are in GA4, which ones to use, their API names, the limits per property and how to create a custom dimension step by step.

Published on
19/11/2026
Updated on
19/11/2026
Reading time
17 min
Google Analytics Dimensions: What They Are and How to Use Them in GA4

Tools

On this page

In short

A Google Analytics dimension is a text attribute that describes your data, such as the country of a visitor, the device they used or the page where their session started. Dimensions give context to metrics like sessions or conversions. Start with the built-in dimensions, and create a custom dimension only when that list cannot answer your question, within your property's limits (50 event-scoped and 25 user-scoped on a standard property).

Want to go further? Ask

Quick quiz

Which way of measuring your marketing fits you?

Question 1 of 425%
What do you want to know first?

What a dimension is, and how it differs from a metric

Every number in a GA4 report has a label. The number is a metric. The label is a dimension. "412 sessions" is a metric. "412 sessions from Germany on mobile" adds two dimensions, country and device category, that tell you which visitors produced that number.

Google's Analytics Help reference uses the same split. Dimensions are descriptive attributes, and they are text or categories. Metrics are quantities. Averages, rates and percentages count as metrics, even when they are calculated from other metrics. You can add up sessions across rows. You cannot add up countries. You group by them.

This is why the same metric can mean different things. An engagement rate of 60% on a landing page reads very differently once you know the visitors came from your newsletter and not from a paid campaign. The dimension tells you who arrived. The metric tells you how many of them did something.

If GA4 itself is new to you, read our GA4 glossary entry first, then come back here. This guide assumes that data already flows into a GA4 property.

Dimension or metric?

Dimension
  • Text or category: country, device, page path
  • Answers who, what and where
  • Cannot be summed up
Metric
  • Number: sessions, active users, conversions
  • Can be summed, averaged or divided
  • Gives no context on its own

Why the model changed from Universal Analytics

Older guides describe "custom dimension index 1" and hit-level scopes. That world is over. Google stopped processing new hits for standard Universal Analytics properties on July 1, 2023. The 360 properties that had a current order got extra processing time until July 1, 2024. If your team still talks in index numbers, translate that habit. In GA4 you give each custom dimension a name, and you point it to a parameter that your site or app sends.

Universal Analytics end dates

July 1, 2023Standard Universal Analytics properties stop processing new hits.
July 1, 2024Extra processing time ends for 360 properties that had a current order.

Source: Google Analytics Help, "Google Analytics 4 has replaced Universal Analytics"

The 16 dimension categories in GA4

Google's Analytics Help page on dimensions and metrics groups the built-in dimensions into 16 categories: Attribution, Demographics, Ecommerce, Event, Gaming, General, Geography, Link, Page / screen, Platform / device, Publisher, Time, Traffic source, User, User lifetime and Video. The same page also lists 11 metric categories, such as Session, Revenue and Advertising. Keep the two lists apart when you search, because a metric category will not help you filter by country.

Google's reference table of GA4 dimensions and metrics, grouped by category
Google's reference groups the built-in dimensions into 16 categories.

You do not need to memorize the list. You need to know which category holds the answer to your question. Four categories cover most of the work on a content site:

  • Traffic source tells you where a session started: search, social, referral or a campaign.
  • Page / screen tells you what the visitor saw, starting with the page path and the page title.
  • Platform / device tells you the device category, the browser and the operating system.
  • Geography tells you the country and the city.

Event and User dimensions come next. Event dimensions describe an action, such as a button click or a video play. User dimensions describe the visitor across sessions, such as the source that first brought them to your site. Knowing this split tells you whether a question belongs to a session, an event or a user. Mixing those levels is one of the most common reasons a report looks wrong, and we come back to it in the mistakes section.

Blue data points on a grid, each tagged with a label such as country, device or page
Dimensions label the numbers: the same metric means something different once you know where it came from.

The standard dimensions you will use most, with their API names

Each dimension has two names. The UI name is what you see in a report. The API name is what you send to the Google Analytics Data API, and you need it for exports, scripts and dashboards. Google documents the API names in its Data API schema. The table below covers the dimensions most content sites use.

UI nameAPI nameAnswers the question
Session sourcesessionSourceWhich site or platform started the session
Session mediumsessionMediumWhich type of traffic it was, such as organic, referral or cpc
Session default channel groupsessionDefaultChannelGroupWhich channel group the session belongs to
Landing pagelandingPageThe first page of the session
Page pathpagePathThe path part of each page the visitor opened
CountrycountryWhere the user activity came from
Device categorydeviceCategoryDesktop, tablet or mobile
Event nameeventNameWhich event was recorded
DatedateThe event date, formatted as YYYYMMDD
Google's Data API schema page listing standard dimension names
Each dimension has an API name, and that is the name you send in a request.

Three rules help when you move between the interface and the API. First, API names are case-sensitive, so sessionSource is not SessionSource. Second, each extra dimension splits every row into more rows, which makes the output harder to read, so start with two or three. Third, a request that names a dimension your property does not know will fail. That last point matters most for custom dimensions.

Reading a custom dimension in the API

Custom dimensions use a different pattern. Google's schema references them by scope and parameter name. An event-scoped dimension is written as customEvent: followed by the parameter name. A user-scoped dimension is written as customUser: followed by its parameter name. The example below asks for session source and an event-scoped custom dimension called author_name, over the last 28 days. Replace the names with your own.

{
  "dimensions": [
    { "name": "sessionSource" },
    { "name": "customEvent:author_name" }
  ],
  "metrics": [{ "name": "sessions" }],
  "dateRanges": [{ "startDate": "28daysAgo", "endDate": "yesterday" }]
}

This request works only if your property has registered author_name as an event-scoped custom dimension. Otherwise the request fails. Register first, then query.

Note

Dimensions registered before October 2020 use a longer form that includes the event name in brackets, such as customEvent:parameter_name[event_name]. If a query that worked last year fails now, check whether the dimension is one of these legacy ones.

Primary and secondary dimensions in reports

A primary dimension is the one a report is grouped by. Each row is one value of that dimension. A secondary dimension adds a second breakdown inside each row. The idea is simple, but it is where most people get stuck, because the same data answers a different question depending on which dimension comes first.

QuestionPrimary dimensionSecondary dimensionWhat you learn
Which pages get organic visits?Landing pageSession source / mediumWhether search is the main source for each page, or whether the page depends on other channels
Are visitors from a market mostly on phones?CountryDevice categoryThe mobile share for each country, which tells you where to test layouts first
Which campaigns land on which pages?Session campaignLanding pageCampaigns sent to pages that do not match their offer
Which browsers do visitors from one country use?BrowserCountryCompatibility problems that only appear in one market

You can stack more than two dimensions in an Explorations table, but readability drops fast. Keep to two or three in one view, and move the rest into filters. A filter removes rows, and a dimension splits them. Use filters to narrow the question, and dimensions to explain the answer.

Why the order changes the answer

Take the first row of the table above. If Landing page is primary and Session source is secondary, each row is a page with its traffic split by source. Flip them, and each row is a source with its pages listed underneath. The numbers are identical. The question is different. Decide which one you need before you open the report, and write it down in one sentence.

Custom dimensions: when you need them and what they cost

Standard dimensions cover most reporting. You need a custom dimension when the information lives in your own system, or in a parameter you send yourself. Typical cases are an author name on a blog, a plan type in a SaaS app, a content category, or whether the visitor was logged in. Before you create anything, ask one question: could the built-in list answer this? If yes, stop there.

Event-scoped, user-scoped and item-scoped

The scope decides what a custom dimension describes. An event-scoped dimension attaches to one event, such as a click or a page view that carries a parameter. A user-scoped dimension attaches to a visitor and keeps the same value across their sessions, such as a plan tier. An item-scoped dimension attaches to one item inside an ecommerce event, such as the colour of a product.

ScopeAttaches toTypical useStandard property360 property
Event-scopedOne eventAuthor of the article that was read50125
User-scopedOne visitorPlan tier, logged-in status25100
Item-scopedOne item in an ecommerce eventProduct brand or colour1025

Custom dimension limits on a standard property

50event-scoped custom dimensions
25user-scoped custom dimensions
10item-scoped custom dimensions

Source: Google Analytics Help, custom dimensions and metrics overview

Event-scoped custom dimensions, standard vs 360

Standard property50
360 property125

Source: Google Analytics Help, custom dimensions and metrics overview. Bar lengths are relative to 125.

Quota, and what happens when you hit it

The limits apply per property, and they count every registered dimension. The Custom definitions page in Admin shows your usage. Open the Quota information link at the top right to see how many slots you have left. Keep that page open whenever you plan a tracking change.

If you reach the limit, freeing a slot is not instant. Google's help page on custom dimension limits says you must wait 48 hours after deleting dimensions before you can add new ones. Plan your names before you start, and avoid creating a dimension for a one-off test that you will delete next week.

Google's help page on custom dimensions and metrics, with the quota table
The quota table gives the limits for standard and 360 properties.

Warning

Never send personal data as a dimension value. Names, email addresses and phone numbers are personally identifiable information, and Google's rules forbid sending them to Analytics. An author name is fine. A customer's email address is not, even if it is hashed in your code.

How to create a custom dimension, step by step

These steps assume that your site or app already sends the parameter. If no data arrives, the dimension is created but it shows nothing. Work through the list in order.

Create a custom dimension in five steps

  1. Send the parameterAdd the event parameter or user property to your tag or code, trigger it, and confirm the value in DebugView.
  2. Open Custom definitionsIn Admin, open the Custom definitions page and click Create custom dimension.
  3. Choose the scopePick event-scoped or user-scoped. Pick item-scoped only if your store sends item parameters.
  4. Enter the exact parameter nameType it exactly as your code sends it, with the same underscores and case.
  5. Wait for reportingData starts to appear 24 to 48 hours after you create the dimension.

Source: Google Analytics Help, "[GA4] About custom dimensions and metrics"

Check the value before you register it

Open DebugView, then trigger the event on your site or in your app. Look at the event and its parameters. Confirm that the value is the one you expect, for example "Jane Doe" for an author and not "undefined". Only then create the dimension. A parameter that sends the wrong value will fill your reports with wrong data from that day on, and the earlier days cannot be corrected.

Match the name in your code and in the interface

The parameter name in the interface must match the name your code sends. A one-letter difference, an uppercase letter or a space creates a dimension that never fills. Copy the name from your code instead of typing it from memory. Use lowercase letters and underscores, as in author_name, because you will paste the same string into API requests later.

Note

Google's help page on GA4 custom dimensions says reporting starts 24 to 48 hours after you create a dimension. Do not create a dimension on the afternoon of a campaign launch and expect the data the same day. Create it a few days early, then check it.

Four ways to use dimensions: reports, Explorations, the API and Looker Studio

Once dimensions exist, you can read them in four places. Each one suits a different job. Choosing the wrong tool costs you time, so compare them before you build anything.

MethodBest forMain limitExample
Standard reportsQuick checks on traffic, pages and eventsFixed layouts with one primary and one secondary dimensionTraffic acquisition by session source
ExplorationsCustom tables, funnels and path analysisTakes setup, and large tables get slowLanding page by session source and device category
Data APIExports, scripts and your own dashboardsNeeds code, and every dimension must be registeredWeekly export of sessions by page to a spreadsheet
Looker StudioShared reports for clients or managersDepends on the connector and its refresh scheduleMonthly client dashboard with traffic by channel

Standard reports first

Standard reports answer the first question you have each morning. Use them to spot a drop, then move to a more flexible tool to find the cause. Their advantage is speed. Their weakness is that you cannot choose any dimension pair you like, so a question that needs three dimensions will not fit in a standard report.

Explorations for the questions reports cannot answer

Explorations let you build a table with the dimensions and metrics you choose, and you can save it for later. This is the tool for landing page analysis, for comparing channels inside one country, and for checking whether a custom dimension really fills. Keep each exploration to one question. A table that answers five questions usually answers none of them clearly.

Tip

Clean dimensions start with clean campaign links. Source and medium values come from your UTM parameters, so a spelling difference such as "Newsletter" and "newsletter" creates a second row for the same channel. Build your links with our free UTM Link Builder so the names stay consistent.

The Data API for anything you repeat

Use the API when a report runs every week, when you feed a dashboard, or when you want to compare the output of two properties in a script. The request pattern shown earlier in this guide is the building block. Once it works in a test, put the same JSON in your script, and keep the dimension names in one place, so a rename does not break ten queries at once.

Looker Studio for shared dashboards

Looker Studio is the usual choice when someone else needs to read the numbers. It connects to GA4 and presents the dimensions as charts and tables. Its limits come from the connector and its refresh schedule, not from GA4 itself. If you are building a client dashboard, our guide to Looker Studio for SEO covers the formulas and limits that matter for search data, and our guide to a GA4 dashboard covers what to put on the first screen.

Measure AI traffic with dimensions

AI assistants send visitors who arrive through a link, and that link carries a referral source. You can see this in the session source dimension and in the landing page. Some AI apps do not pass a referrer at all, so this method captures only part of the picture. Our glossary entry on AI dark traffic explains what is missing and why. For organic search in the same report, our guide to Google Analytics for SEO shows how to separate it from the rest.

Isolate AI visits in four steps

  1. Open an ExplorationUse a free form table and add Session source as the row dimension.
  2. Add the landing pageAdd Landing page as a secondary dimension to see which pages AI visitors reach first.
  3. Filter to AI sourcesFilter session source to the AI assistants you care about, such as chatgpt.com or perplexity.ai. Check the exact names in your own report first.
  4. Save and compareSave the exploration and compare it each month with organic search from Google, using the same date range.

Read the result with care. A rise in AI sessions on one page tells you that the page is being used, but it does not tell you whether the visitors bought anything. Add a conversion metric to the table before you decide that a page works. The article on measuring AI citations with Google Analytics walks through the conversion side.

Tip

If you want Google and AI traffic on one screen without building the exploration yourself, Sorank's GEO / SEO dashboard shows both, combining Google Search Console data (clicks, impressions, CTR, position) with the page views that AI assistants send, as recorded in Google Analytics.

Common mistakes, and how to fix them

Most dimension problems show up as an empty column, a column of "(not set)" values, or a report that looks correct but answers the wrong question. The table gives you the sign to look for. The sections below explain each mistake.

MistakeHow to spot itFix
Creating a dimension before data arrivesEvery row shows "(not set)"Confirm the value in DebugView first, then create the dimension
Name mismatch between code and interfaceNo data 48 hours laterCopy the parameter name from the code
Duplicating a built-in dimensionTwo dimensions give the same rowsReview the standard list first, then delete the copy
High-cardinality valuesThousands of rows, each with one sessionSend categories, and keep unique IDs in your own system
Personal data in a valueValues that look like emails or full namesRemove the parameter and send a category instead
Expecting historyOld dates are empty, new dates are filledCompare only from the creation date onward, and note the gap

Creating a dimension before the data arrives

The mistake: you create the dimension, then find that the parameter never reached GA4. You can spot it because every row in the report shows "(not set)". The fix is to reverse the order. Confirm the value in DebugView, then register the dimension, then wait for the 24 to 48 hours that Google describes before you judge the report.

A name that differs by one character

The mistake: the code sends author_name, and the interface holds Author_name or author name. The dimension exists, and it stays empty. The sign is a clean custom definition with zero data after two days. The fix is to open the code, copy the exact string, and check it again in DebugView. Fixing it later does not restore the lost days, so fix it the day you find it.

Duplicating a built-in dimension

The mistake: you create a custom dimension called Country, because you did not check the standard list. You can see it in two rows that carry the same values. The cost is quota. Every duplicate uses one of your 50 event-scoped slots, or one of your 25 user-scoped slots, and those slots are the ones you need later for things GA4 cannot give you. Review the standard list in the reports first, then decide.

High-cardinality values

The mistake: you send a dimension with a value that is unique to each visitor or each order, such as a user ID, a full URL with a query string, or an order number. Google advises avoiding high-cardinality dimensions in standard properties. The sign is a table with thousands of rows, each one holding a single session. The fix is to send a category instead. Send plan type, not user ID. Send content type, not the full URL. Keep the unique identifier in your CRM, where you can join it back to the data yourself.

Personal data in a value

The mistake: a dimension holds an email address, a name or a phone number, often because a developer used a convenient variable. The sign is a value that looks like a person. The fix is to remove the parameter, and to send a category or an anonymous internal code. Check this with your data protection contact if you are unsure. Hashing an email address does not make it safe to send.

Expecting history

The mistake: you create a dimension in May and expect it to explain the sessions from January. Reports can only show values that were collected after the dimension started to receive them. The sign is an empty column for the earlier dates. The fix is to state the start date in the report title, and to compare only from that date onward. Do not present a before and after chart that starts in the middle of a gap.

Questions people ask, and a checklist for this week

What is the difference between a dimension and a metric in Google Analytics?

A dimension is a text attribute, such as country, device or page path. A metric is a number, such as sessions, active users or conversions. Dimensions group and label the numbers, so the same metric reads differently depending on the dimensions you pair with it.

How many custom dimensions can I create in GA4?

A standard property allows 50 event-scoped, 25 user-scoped and 10 item-scoped custom dimensions. A 360 property allows 125, 100 and 25. The Custom definitions page in Admin shows how many you have used. Deleting one does not free its slot instantly, because you must wait 48 hours before you can add a new one.

Why does my new custom dimension show no data?

Usually the parameter does not reach GA4, or its name does not match exactly. Check DebugView, fix the name in the interface or in your code, and wait 24 to 48 hours after creation. If the data still does not appear, the parameter itself is probably not being sent.

Your checklist for this week

  • List the standard dimensions your reports already use
  • Write one question that each custom dimension must answer
  • Send the parameter and confirm it in DebugView
  • Create the dimension with the exact parameter name
  • Note your quota in the Custom definitions page
  • Check the report 48 hours later, and fix any empty column the same day

Start with one question you cannot answer today. Build one dimension for it, check the data, and only then add the next one.

Frequently asked questions

What is the difference between a dimension and a metric in Google Analytics?

A dimension is a text attribute, such as country, device or page path. A metric is a number, such as sessions, active users or conversions. Dimensions group and label the numbers.

How many custom dimensions can I create in GA4?

A standard property allows 50 event-scoped, 25 user-scoped and 10 item-scoped custom dimensions. A 360 property allows 125, 100 and 25. The Custom definitions page in Admin shows your usage.

Why does my new custom dimension show no data?

Usually the parameter does not reach GA4, or its name does not match exactly. Check DebugView, fix the name, and wait 24 to 48 hours after creation before you judge the report.

Get your content plan for 30 days for free

We analyse your competitors, your website and your AI visibility to create a tailored content plan for free.

Our free SEO tools

See all our free tools

Get your content plan for 30 days for free

We analyse your competitors, your website and your AI visibility to create a tailored content plan for free.

Man with dark hair and beard wearing a light brown shirt speaks in front of a microphone on a podcast or recording setup.Portrait of a man with short dark hair wearing a white shirt and dark jacket, looking directly at the camera with a neutral expression.Man with short dark hair, beard, and clear glasses wearing a black t-shirt with a white circular logo, standing in front of a stone wall.Celio fabianoSmiling young woman with long brown hair wearing a red top and necklace, outdoors in a tree-filled background.Profile photo of Xavier Breull, Sorank customer
Google
Solid yellow five-pointed star icon on transparent background.Solid yellow five-pointed star icon on transparent background.Solid yellow five-pointed star icon on transparent background.Solid yellow five-pointed star icon on transparent background.Solid yellow five-pointed star icon on transparent background.
5/5
+5,000
users

Testimonials from ambitious founders

0 to 10000 visitors in 5 months

Celio Fabianomonrobotlavevitre.frGoogleE-commerce

0 to 5000 visits in 8 months

Thibault BMsorank.comGoogleSoftware

0 to 1104 clicks in 4 months

Dominiqueflight-sensations-idf.comGoogleLeisure and aviation

0 to 163 clicks in 6 months

Coworking Pariscoworking-paris.frGoogleOffice broker

x92 clicks in 7 months

Guide Zanzibarguidezanzibar.comGoogleTravel