How do I export an AI referral report with the GA4 Data API?

Definition: An AI referral report from the Google Analytics Data API is a table of website activity filtered to selected assistant source values. A runReport request specifies the Analytics property, reporting period, dimensions that group the rows, metrics that measure activity, and source filter.

Key facts

• As of 17 October 2026, Google's reporting guide recommends runReport for core reporting queries.
• Google's API schema defines sessionSource as the source that initiated a session and sessionMedium as its medium.
• Google's filter reference provides inListFilter for matching a list of string values, with a caseSensitive setting.
• The request reference sets a default of 10,000 rows and a maximum of 250,000 rows per request.

Which dimensions and metrics belong in the report?

Google's API schema distinguishes session attribution from user acquisition: firstUserSource identifies the source that first acquired a user, while sessionSource identifies the source that initiated a session. A report about assistant-referred sessions uses sessionSource, optionally paired with sessionMedium to separate medium values within each source.

The sessions metric counts sessions that began on the site or app. The keyEvents metric counts events marked as key events, which represent selected outcomes; marking an event as key affects reporting from that point onward. For the share of sessions with an outcome, sessionKeyEventRate measures the percentage of sessions in which any key event occurs.

For an entry-page breakdown, landingPagePlusQueryString adds the page path and query string associated with the session's first pageview.

What does the source-filtered request look like?

Google's quickstart covers enabling the Data API, granting the authenticated account property access, and obtaining credentials. Its read-only authorization scope is https://www.googleapis.com/auth/analytics.readonly.

The following illustrative request selects the literal source value chatgpt.com. The source list is an editorial selection for this report; additional values should come from the property's recorded source data. In Google's filter reference, inListFilter accepts a non-empty list, and caseSensitive: false makes matching insensitive to letter case.

Save this body as request.json:

{
  "dateRanges": [{"startDate": "7daysAgo", "endDate": "yesterday"}],
  "dimensions": [
    {"name": "sessionSource"},
    {"name": "sessionMedium"}
  ],
  "metrics": [
    {"name": "sessions"},
    {"name": "keyEvents"}
  ],
  "dimensionFilter": {
    "filter": {
      "fieldName": "sessionSource",
      "inListFilter": {
        "values": ["chatgpt.com"],
        "caseSensitive": false
      }
    }
  },
  "limit": "10000"
}

With the property ID in PROPERTY_ID, the Cloud project ID in PROJECT_ID, and an authorized access token in ACCESS_TOKEN, this request saves the response as JSON:

curl --fail-with-body -sS -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/${PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  -o ai-referrals.json

Google's request reference places source conditions in dimensionFilter. A metricFilter applies after row aggregation and accepts metric conditions. This example leaves sessionMedium unrestricted and returns its recorded values as separate rows.

How does the response become a complete export?

Google's response reference defines dimensionHeaders and metricHeaders in the same order as their corresponding row values. A CSV conversion can use these headers as column names and concatenate each row's dimension values and metric values.

The response's rowCount is the total number of result rows, independent of the requested page size. Google's pagination instructions use limit and offset to retrieve successive pages. If rows remain, repeat the same query with an offset equal to the number already retrieved and append the returned rows.

Related terms

• AI referral traffic
• GA4 traffic acquisition
• Key events from AI referrals
• How do I find ChatGPT referral visits in GA4?

FAQ

Can I combine several assistant sources?

Yes. You can add their recorded source strings to inListFilter.values. Google's reporting guide states that this filter matches any value in the list.

How do I check a different combination of fields?

You can submit the proposed fields to Google's checkCompatibility method. It checks compatibility for core reports; incompatible dimensions and metrics cause reports to fail.

Sources

1. Google, "Create a report", updated 13 October 2026
2. Google, "API dimensions and metrics", updated 13 October 2026
3. Google, "FilterExpression", updated 6 October 2026
4. Google, "Method: properties.runReport", updated 23 April 2026
5. Google, "Google Analytics API quickstart", updated 13 October 2026
6. Google, "RunReportResponse", updated 23 April 2026
7. Google, "Method: properties.checkCompatibility", updated 23 April 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer