Google Analytics

Connect a Google Analytics 4 (GA4) property to a NameIO project. Its organic search traffic then shows on the project dashboard, and your own AI agent can run read-only GA4 reports through the NameIO MCP server. NameIO reads GA4 data live from Google and has no write access to your property. Google Analytics data uses no credits.

Before you start

• Only organization owners and admins can connect, change or disconnect a GA4 property.
• Sign in to Google with an account that can see the GA4 property you want to use.
• Finish the Google steps within 10 minutes, ideally in a single browser tab.

GA4 isn't part of signup. You connect it separately for each project, and each project connects to one GA4 property.

Connect a property

1. Open the project and select Project settings. It's the gear button next to the project switcher in the sidebar, and there is also a Project settings button on the project dashboard.
2. Open the Integrations tab. The Google Analytics card comes second, after the Search Console card.
3. Select Connect. The button reads "Opening Google…" while NameIO sends the page to Google.
4. Choose your Google account. Google always shows its account chooser, then its permission screen.
5. Google may show a "Google hasn't verified this app" screen before the permission screen. To continue, select Advanced, then the Go to … (unsafe) link.
6. On the permission screen, check every box, then continue.
7. Google sends you back to the Integrations page, and the property picker opens on its own.
8. Select Select a property… to open the list. Properties are grouped under the email of each Google account. To filter them, type in Search properties or accounts…. Each property shows its GA4 name, followed by the GA4 account name and the numeric property ID.
9. Select your property, then select Save property. NameIO confirms with "Google Analytics connected".

When you save, NameIO checks that the property belongs to that Google account. It then stores the property's display name, time zone and currency. Reports use that time zone to decide which day counts as yesterday.

After you connect, the card shows the property name, its ID and the Google email that connected it. It also has two buttons: Change property or account and Disconnect project. If you close the picker without saving, the card reads "Choose a Google Analytics property to finish connecting this project." Select Choose property to finish.

You can also connect from the project dashboard. Until GA4 is connected, the dashboard shows a card titled "Do you use Google Analytics 4?". Yes, connect GA4 opens the same connection card on the dashboard, with Connect and Dismiss buttons. After Google, you come back to the dashboard and the question card shows again. Select Yes, connect GA4 again to open the property picker and finish. No or Dismiss hides the card. NameIO then suggests connecting your analytics provider's MCP server to your AI agent instead.

Accounts and properties

The picker lists every GA4 property your Google account can see, and you can select any of them. To link another Google account, use Add Google account at the bottom of the picker. If you save a different property later, it replaces the current one.

A Google account in the picker can show one of these states:

What NameIO can access

GA4 has its own Google grant, separate from Search Console and from Google sign-in. NameIO asks Google for openid, email, profile and https://www.googleapis.com/auth/analytics.readonly. It doesn't ask for any write access to Google Analytics.

Reports always run on the Google grant of the person who connected the property. If that person removes their Google account from NameIO, the project's GA4 connection goes with it.

Google tokens are encrypted at rest. The NameIO privacy policy says NameIO's use of Google API data follows the Google API Services User Data Policy, including its Limited Use requirements.

If connecting fails

If the connection fails, the card usually shows a red alert:

If the attempt expires (more than 10 minutes) or is interrupted, you land on a separate page titled "Google sign-in didn't finish" with the code state_mismatch. Select Back to NameIO, then connect again in a single browser tab within 10 minutes, and check that your browser allows cookies for NameIO.

The Organic traffic card

Once GA4 is connected, the project dashboard shows a card titled Organic traffic, labelled "Google Analytics · Last 28 days". It counts Organic Search traffic only.

The card shows Sessions, Active users, Engagement rate and Key events. Every metric except Engagement rate also shows its change from the previous 28 days as a whole-number percentage, when the previous period had a value above 0. Below the metrics is a daily Sessions chart, and days with no sessions show as 0. To get to the connection card, select Manage.

The card can also show:

• "No organic search traffic recorded in the last 28 days yet." when GA4 has no Organic Search sessions for the period.
• "Couldn't load Google Analytics data. Try again shortly." when Google doesn't return the data, including when Google's reporting quota is used up.
• The Google Analytics connection card, in place of the report, when the Google grant has expired or the property is no longer accessible. Select Change property or account, open the property list, then select Reconnect next to the expired account, or choose another property.

Use GA4 reports in your AI agent

To run other GA4 reports, connect your AI agent to the NameIO MCP server (see MCP) and use its ten GA4 tools. They are all read tools: a connection with only the read-only mcp scope can use them, and mcp:write isn't needed.

Every tool takes a projectId. NameIO then uses the Google account and property saved for that project. Most report tools share these inputs. The organic overview takes only the dates and trend. get_search_opportunities takes only the dates and its own limit, with its own default range (see below). It has no offset, and it moves a late endDate back to yesterday without an end_date_clamped warning. The shared inputs:

• startDate and endDate: YYYY-MM-DD dates. Pass both or neither. Without them, a report covers the last 28 days, ending yesterday in the property's time zone. If endDate is later than that, it's moved back to yesterday and you get an end_date_clamped warning.
• limit (1 to 1,000, default 100) and offset (default 0). The tool tells you when there are more rows, so you can page through them with offset.
• channel: on reports that offer it, organic_search (the default) or all. If one of these reports comes back empty with channel=organic_search, the tool says: "This report is filtered to Organic Search. Pass channel=all to include every channel."
• comparePreviousPeriod: compares the range with the period of the same length just before it. It works only for key events with the event breakdown, traffic acquisition by channel group, and audiences by device or by new versus returning. The text output shows up to 50 comparison rows.

The tools:

• get_google_analytics_organic_overview: Organic Search totals for sessions, active users, engaged sessions, engagement rate, key events, transactions and purchase revenue. Each total is compared with the previous period of the same length, and there's a daily (default) or weekly trend. The trend stops at 1,000 rows and adds a trend_truncated warning when it hits that limit. If key events fall by 50% or more from a previous period that had at least 5, the result's diagnostics include key_events_sharp_decline.
• get_google_analytics_organic_landing_pages: Organic Search landing pages by host. Shows sessions, active users, engaged sessions, engagement rate, key events, session key event rate, transactions and purchase revenue, sorted by sessions. It has no channel option.
• get_google_analytics_page_performance: pages by host and path, with views, active users, user engagement duration and key events, sorted by views. Set includeDate=true to add the date. Organic Search by default, or channel=all.
• get_google_analytics_key_events: events with at least one key event, showing key events and total users. Set breakdown=event_and_landing_page to add host and landing page. Organic Search by default.
• get_google_analytics_ecommerce_performance: with breakdown=item (the default), item name and ID with items viewed, added to cart and purchased, and item revenue, sorted by item revenue. With breakdown=landing_page, sessions, transactions and purchase revenue for each landing page, sorted by revenue. Add onlyWithTransactions=true to keep only pages with transactions. Organic Search by default. The result has an ecommerceActivity status of detected, none or unknown. none adds a no_ecommerce_activity diagnostic.
• get_google_analytics_site_search: internal search terms from view_search_results events, excluding "(not set)". Shows event count, active users, sessions, engaged sessions and engagement rate, always across every channel. It needs GA4 site-search measurement. The result has a siteSearchActivity status, plus a no_site_search_activity diagnostic when there are no searches.
• get_google_analytics_audience_breakdown: active users, sessions, engagement rate and key events by device (the default), country, or new versus returning. Organic Search by default.
• get_google_analytics_traffic_acquisition: sessions, active users, engaged sessions, engagement rate, key events, transactions and purchase revenue across every channel. Breaks down by channel group (the default), source/medium or campaign. The source/medium breakdown adds attribution diagnostics: a "(not set)" share of 5% or more, referrers from local or private networks, and source/medium values that differ only in letter case.
• get_google_analytics_measurement_health: reads the property's settings, not report data. Its only input is projectId. It returns:
  • data streams, including each web stream's measurement ID, default URI and enhanced-measurement settings
  • key events and their counting method
  • custom dimensions and metrics
  • these issue codes: no_web_stream, enhanced_measurement_disabled, site_search_measurement_disabled and no_key_events_configured
• get_search_opportunities: joins Search Console pages with GA4 organic landing pages. See the next section.

Search opportunities

get_search_opportunities needs both Search Console and GA4 connected to the project. It works in four steps:

1. It fetches up to 1,000 Search Console page rows (web search, final data) and keeps the pages with an average position from 4 to 20.
2. It matches each page to a GA4 organic landing page by normalised host and path.
3. It scores each match as round(100 × (0.5 × demand + 0.3 × business value + 0.2 × reachability)):
   • Demand is the page's percentile for log impressions.
   • Business value is its percentile for session key event rate. If no matched page has key events, engagement rate is used instead.
   • Reachability is its percentile for 20 minus its position.
4. Pages with no GA4 match stay in the list, without a score.

limit runs from 1 to 100 (default 50). Without dates, the range is 28 days ending 3 days before today, in the GA4 property's time zone. Search Console dates use Pacific Time, so you get a source_time_zones_differ warning when the GA4 property uses a different time zone.

Freshness and data limits

NameIO fetches GA4 reports live from Google on every request and doesn't cache them on its servers. While NameIO stays open in your browser, the dashboard card reuses its data for 5 minutes after it loads. After that, it refreshes in the background the next time you open the dashboard or return to the tab. Reloading the page fetches it again.

NameIO treats yesterday, in the property's time zone, as the last complete day. Google says standard daily data typically takes 12 hours to process, that "Data processing can take 24-48 hours", and that reports can change in that time. Figures for the most recent days may still change.

Every report includes Google's report metadata:

• subjectToThresholding
• sampling, with samplesReadCount and samplingSpaceSize
• dataLossFromOtherRow
• restrictedMetrics
• emptyReason

If the report is thresholded or sampled, lost rows to "(other)", or has restricted metrics, reportMetadata.hasLimitedData is true. Except for the organic overview and get_search_opportunities, the tool's text also says "Google marked this report as limited; inspect reportMetadata." Google applies data thresholds automatically, and they can't be adjusted. They hide some rows so that viewers can't infer anyone's identity.

A metric the Google user isn't allowed to see, such as revenue, comes back as null rather than 0. On limited or incomplete data:

• ecommerce and site-search activity read unknown
• the source/medium diagnostics are left out
• the key-event decline diagnostic is left out

Reports also include Google's property quota as quota. It covers tokens per day and per hour, concurrent requests, potentially thresholded requests per hour, and other limits.

Errors in your AI agent

When a GA4 tool can't run, it returns one of these codes:

get_search_opportunities can also return a Search Console code (gsc_not_connected, gsc_api_disabled, gsc_reconnect_required or gsc_upstream_unavailable); see Google Search Console.

The first three errors end with "Continue here:" and a link to the project's Integrations settings. Reconnect there.

Disconnect or remove access

To stop one project using GA4, select Disconnect project on its connection card. This takes effect straight away, with no confirmation step. The button reads "Disconnecting…", then NameIO shows "Google Analytics disconnected from this project". Only that project's property link is removed. Your Google grant stays linked to your NameIO user, so you can pick a property again without going back to Google, until the daily cleanup described below removes grants no project uses.

To remove a Google account's Google Analytics access from NameIO:

1. On the connection card, select Change property or account.
2. Open the property list (the button showing the current property), then select Remove account next to the Google account.
3. Read the "Remove Google account?" dialog. It tells you how many projects will be disconnected from Google Analytics, or that no projects will be affected.
4. Select Remove account. NameIO confirms with "Google account removed".

Removing the account deletes its Google Analytics grant and disconnects every project that used it. NameIO then revokes the token at Google, unless a Search Console or Google Analytics grant in NameIO still uses that Google account, such as another NameIO user's grant or your own Search Console grant. Your Google sign-in to NameIO doesn't count. NameIO waits for the last grant because Google revokes all of an app's permissions for an account at once.

Once a day, at 03:17 UTC, NameIO deletes Google Analytics grants that no project uses and that were linked or last refreshed more than 24 hours earlier. It revokes them at Google under the same last-grant rule.

What's not done

• The Organic traffic card is the only GA4 report inside the app. All other GA4 reports run through MCP in your own AI agent.
• Audience breakdowns have no demographic or user-level dimensions.