AI referral traffic report for assistant visits in GA4.

Run this report from the CLI, an MCP client, or application code. Every surface uses the same report definition and returns the same evidence. JSON is the source of truth; Markdown makes it readable without hiding dates, limits, warnings, or skipped work.

What this report helps you decide

Which AI products sent referral sessions recorded by this GA4 property?

• You need observed referral evidence rather than an AI visibility estimate.
• The GA4 property and date range are known.

Command facts

Report id

ai-referrals

Execution

Local process

Outputs

JSON and Markdown

Example parameters

property, startDate, endDate, resultLimit

Agent discovery

seo reports describe ai-referrals --json

Interactive prompts

Human CLI commands only

When this report is not the right tool

These cases need a different report, more evidence, or a human decision. Do not force this report to answer a question its data cannot support.

• You want to know whether important pages are technically available to AI search systems, regardless of whether GA4 recorded a visit. Recommended report: Check AI search technical readiness. Run AI readiness. It checks crawl, index, snippet, and page-structure evidence that referral analytics cannot see.
• You need to know whether assistants mention or cite the site even when nobody clicks through. No automated report in this package measures unclicked mentions or citations. Use repeatable external prompt monitoring and inspect the answers and cited URLs. AI referrals can only confirm visits that reached GA4 with a recognisable source.

Data sources and inputs

• GA4 traffic acquisition rows. Provides session source, landing page, sessions, engagement, and the selected date scope.
• Documented AI referral source rules. Defines which returned source values are included in the AI referral result.

What this report checks

• Matches returned session-source rows against explicit known AI referrer rules.
• Aggregates matching sources and landing pages while leaving unclassified traffic outside the AI total.

How it works

• Filters returned acquisition rows by explicit source rules, aggregates matches, and keeps unclassified traffic out of the AI total.

The JSON result keeps dates, thresholds, limits, skipped work, and source completeness beside the finding. Missing, partial, capped, filtered, and complete data remain different states.

Run the report from the CLI

Find GA4 sessions referred by known AI products. Agents and CI should inspect the live schema before their first run.

seo ai-referrals --project example

seo reports describe ai-referrals --json

seo reports run ai-referrals --params '{"property":"123456789","startDate":"28daysAgo","endDate":"yesterday","resultLimit":25}' --json

Project profiles can fill supported property and analytics inputs for the human-facing commands. The catalog form shown here is explicit by design, so agents and CI jobs do not prompt or guess.

How an MCP agent should use it

Call seo_describe_report first so the agent sees when this report is useful and gets the current input schema. Then callseo_run_report with the validated parameters. Read the status, warnings, source limits, and skipped sections before acting on a finding.

{
  "id": "ai-referrals"
}

{
  "id": "ai-referrals",
  "params": {
    "property": "123456789",
    "startDate": "28daysAgo",
    "endDate": "yesterday",
    "resultLimit": 25
  }
}

Use a follow-up report returned by the result instead of guessing the next tool. The local MCP server and CLI use the same report definition and evidence. Their outer transport envelopes differ.

Use the report in a TypeScript app

Install seo as a project dependency, then call the same report catalog used by the CLI and MCP. executeReportrejects an unknown report id or invalid parameters. Provider and runtime failures come back as structured results withisError set.

npm install seo

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'ai-referrals',
  {
  "property": "123456789",
  "startDate": "28daysAgo",
  "endDate": "yesterday",
  "resultLimit": 25
},
)

console.log(result)

The TypeScript library guide also covers direct core functions, schema discovery, and the difference betweenexecuteReport and runReport.

What comes back and how to read it

• AI referral sessions grouped by matched source and landing page with the requested GA4 date range.
• Returned-row limits and caveats for missing referrers, consent, redirects, attribution settings, and source changes.
• Treat returned sessions as attributed referrals from the matched sources. Check the landing-page selection before treating the ranked output as the full retained breakdown, then review those pages and engagement in the same scope.

Start with dataStatus, source details, warnings, and caveats. Then inspect the observed evidence before derived findings or suggested actions.

What this report cannot tell you

• Missing referrers, consent, redirects, attribution settings, and source changes can hide or reclassify visits.

What to do next

1. Inspect the landing pages receiving useful referral traffic.
2. Use a stable prompt corpus if you separately monitor citations or answers.

Related reports

• Find opportunities for one page. See which returned search queries are already associated with one URL and what deserves a closer look on the live page.
• Turn SEO queries into AI prompts. Turn real Search Console queries into prompts for repeatable AI answer monitoring.
• Check AI search technical readiness. Review crawl access, indexability, snippet controls, page structure, and optional agent resources without inventing an AI visibility score.

Sources behind the guidance

These primary sources define the provider data or search controls used in the interpretation above.

• Google Analytics traffic acquisition guidance

Browse all reports in AI search evidence.