Documentation

Import Google Analytics 4 history

Import dated GA4 CSV reports before your first AnalyticFast tracking day. Choose Google Analytics 4 in your website's import settings, upload a CSV or ZIP, preview, confirm the website and timezone, then import. Owners and admins can inspect/manage imports. Viewers can see the resulting analytics, but cannot upload, inspect import history or delete imports.

Export from GA4

  1. Open the correct GA4 property. Use English report labels and confirm its reporting timezone matches the website's AnalyticFast timezone. Choose a date range ending before AnalyticFast tracking began. Turn off date comparisons, segments and filters unless you deliberately want a partial history.
  2. Open Reports, then a detail report such as Traffic acquisition, Pages and screens, Demographic details, Tech details, or Events. For traffic, select Session source / medium rather than first-user source.
  3. Add Date to the actual table using the secondary dimension selector when available. The date range above the chart is not a Date column. Some standard reports cannot add Date; use the free-form alternative below. Do not substitute Day (day of month), Week, Month or Date + hour.
  4. Click Share this report → Download File → Download CSV. These are Google's official report export steps. GA4's own export can contain up to 100,000 rows; AnalyticFast accepts a smaller, bounded import. Read GA4's data-quality indicator: thresholds, sampling, row limits and (other) groups cannot be undone by importing.
  5. Open the CSV in a text editor. It can start with # comment lines describing the report, property, All Users, and start/end date. The following table must have Date alongside the selected dimension. Expected dates are 20230101 (documented GA4 YYYYMMDD) or 2023-01-01. Comments are ignored; their start/end dates are never distributed over data rows.
  6. For the most accurate overview, also export a Date-only table with Total users (or Active users), Sessions, Views, and optionally Engaged sessions / Average session duration. Include it with your breakdowns in one ZIP. Daily totals take precedence over summed breakdown estimates.
  7. To import goals, export Date + Event name + Total users + Key events (older reports use Conversions). Include the matching daily traffic CSV in the same ZIP. Event count alone does not identify goals. Other reports' Key events totals without names are ignored.
  8. For several reports, ZIP the CSV files directly at the archive root, without folders or OS metadata files. Simple English filenames with letters, numbers, spaces, underscores, hyphens, parentheses and dots work. File names do not determine the report type; table headers do.

Google documents detail report customization separately from export. It does not promise one stable CSV serialization contract. This importer recognizes a conservative set of documented English UI/API column names; unsupported layouts produce a helpful error.

When Date is unavailable in a standard report

Use Explore → Free form. Import Date and the desired dimension into Variables; put them in Rows, put the counts in Values, and leave Columns/segment comparisons empty. Use a flat table without nested rows. Export the table as CSV using the exploration's export control. For overview totals, put only Date in Rows. Check the exported CSV actually contains Date and all requested rows; exploration retention/row limits can differ from standard Reports. If you cannot export the full history, use smaller date windows, keeping all report families for each window together.

Do not manually assign the whole report's totals to one day or spread them across days. An undated CSV is rejected even if it contains a start/end comment. Pivoted exports, multiple comparisons, localized labels/numbers/dates, first-user acquisition, page titles, user identities and arbitrary custom dimensions are unsupported. Export a simpler table instead.

Supported columns and mapping

The names and units below follow Google's GA4 dimensions and metrics schema. Each CSV has Date and at most one report family. Country/Region/City may occur together; source/medium/channel/campaign may occur together; page path/hostname may occur together. Combining unrelated families in one table is rejected.

Report familyDimensionsImported history
Daily totalsDate onlyDaily overview visitors, sessions, views, engagement
Traffic acquisitionSession source / medium, or Session source + Session medium; optional Session default channel group / Session primary channel group (Default Channel Group), Session campaignSource/channel and source/medium/campaign filters
Pages and screensPage path and screen class, Page path, or Page path + query string; optional HostnameWeb paths beginning /; native app screen labels are skipped
GeographyCountry / Country ID, optional Region, CityEnglish country names converted to ISO alpha-2; unknown labels skipped with a reason; region/city retain GA4 labels
TechDevice category, Browser, or Operating system, in separate CSVsDevice capitalization normalized; browser/OS names retain GA4 vocabulary
Events / key eventsEvent nameNamed Key events / Conversions become goal completions, stored on daily aggregate rows

Total users (or legacy Users) maps to visitors. Active users is the fallback, with a warning because the user definition differs. Sessions maps to visits; Views maps to pageviews. Missing counts stay zero and are named in preview warnings. Event count is not pageviews and is never treated as goal completions. No revenue, transactions or payment attribution is imported.

Bounces use Sessions minus Engaged sessions when both counts are available; otherwise Bounce rate × Sessions, or (1 − Engagement rate) × Sessions. Rates must be 0..1 or have an explicit %. Duration uses Average session duration × Sessions, otherwise total User engagement seconds, otherwise Average engagement time per active user × Active users. Legacy Average engagement time is accepted with the same requirement for Active users. Duration cells accept seconds or HH:MM:SS. GA4 foreground engagement is an approximation of native session duration. Missing engagement metrics stay zero and make filtered engagement figures incomplete.

Documented Data API header names are also accepted for offline CSV conversions: date, totalUsers, activeUsers, sessions, screenPageViews, engagedSessions, bounceRate, engagementRate, averageSessionDuration, userEngagementDuration, sessionSourceMedium, sessionSource, sessionMedium, sessionDefaultChannelGroup, sessionCampaignName, pagePath, unifiedPagePathScreen, pagePathPlusQueryString, hostName, country, countryId, region, city, deviceCategory, browser, operatingSystem, eventName, keyEvents, and legacy conversions. API JSON itself is not an upload format.

Source names reuse AnalyticFast's shared classifier (for example google → Google, twitter → X, chatgpt.com → ChatGPT). (direct) / (none) becomes Direct/None and Direct. Paid Search/Social/Shopping/Video, Display, Audio and Cross-network map to Paid; Organic Social/Video to Organic Social; Affiliates/Organic Shopping/SMS/push/Unassigned to Referral. Organic Search, Email, Direct and Referral retain their channels. Known AI sources are classified as AI. If no channel column exists, the shared source/medium classifier supplies it. This is an approximation of GA4 attribution, not a recreation of Google's channel rules. Source/medium alone cannot recover the actual referring URL; referrer stays empty.

Totals, skipped rows and goals

Date-only totals supply the overview when present. Otherwise the importer sums exactly one report family, chosen in this order: sources, locations, devices, browsers, operating systems, pages. Preview clearly labels those totals as estimates. It never adds several report families to the overview. Daily totals must cover every breakdown/event date; include matching totals when files have different coverage. If any Date-only totals are supplied, missing dates are rejected rather than filled from another family.

Returning users count again across dates. A person can also appear under several sources/pages/devices. GA4 thresholds, (other) groups, missing exports and truncated rows remain missing. Visitor counts, conversion rate and revenue per visitor therefore use estimated denominators. Daily aggregates appear only in complete local-day/week/month views, not hourly distributions. Cross-report filters exclude history. Revenue and customer counts remain native.

Named key events are stored on existing daily import rows, not in the raw events table. Only positive key-event/conversion rows become goals. Goal visitors are users of that event, which can be an upper-bound estimate of people who actually converted; they are not deduplicated across days. Goals without user metrics have zero known visitors. Goal breakdowns include completions in the existing count field; filtered goal breakdowns exclude imported goals because no joint session/goal distribution exists. Goal properties, funnels, experiments and journeys cannot be reconstructed. Ordinary events with zero key events are skipped explicitly. The reserved internal af_experiment goal is skipped.

Blank-date totals, impossible dates, malformed numeric cells, impossible engagement, unrecognized country names and non-web screen paths are skipped with per-file counts and reasons in preview. Header/encoding/CSV syntax errors fail the upload. Duplicate raw report keys (including repeated/overlapping CSVs), conflicting aliases, unknown columns and incompatible dimensions fail rather than double-counting. Additional known rate, user/revenue-derived metrics are ignored with warnings. CSV quoting, embedded commas/newlines, UTF-8 BOM, LF and CRLF are supported; malformed UTF-8 is rejected.

Confirm, replace or remove an import

Preview writes no analytics rows. Confirm the website and timezone before publication. Imports include only days strictly before the earliest native session/event/retained rollup day and before today. Skipped row counts include invalid CSV rows and rows excluded by this cutoff; warnings distinguish the reasons.

The same normalized data has the same site-scoped digest despite CSV row/column order, filenames or ZIP compression. Confirming it twice keeps the existing import. Any different import whose inclusive date interval overlaps a published Plausible or GA4 import is rejected, even for a gap inside that interval. To add more breakdowns for the same dates, delete the previous import and upload the combined ZIP. Uploading several individual CSVs for the same dates in succession is not additive.

Confirmation recalculates the preview token; a changed file, site timezone or native cutoff needs a new preview. Native data always wins from its first day, including late-arriving older events. Timezone changes exclude old imports until restored or replaced. Staging is invisible to reports; deletion cascades only that import's aggregates and goal counts. A terminated request can leave an unfinished import that an admin can remove before retrying. No raw CSV or ZIP is stored.

Limits and Free-plan costs

Shared upload bounds are 8 MiB ZIP, 12 MiB expanded, 4 MiB per CSV, 16 files, 25,000 input data rows, 4,096 characters per field and 16,384 characters per CSV record. GA4 additionally caps normalized output at 5,000 rows, 512 KiB total JSON and 64 KiB per row, including synthesized daily totals and named goals. These bounds limit memory and staging calls; export smaller date ranges if a limit is exceeded. No schema rebuild or new index on an existing table is required.

Staging reuses the existing JSON insertion batches: at most 250 aggregate rows / approximately 128 KiB per statement, only three bound parameters. Small imports take one insert for the import record, one aggregate insert, one publish update and a confirmation read. Daily goal maps use the same daily row, not an extra write per completion. A typical 30-day example with 20 source rows/day produces 630 aggregate rows (600 source + 30 daily totals), 632 logical row writes (630 + create/publish), and three aggregate insertion statements. Preview performs reads only; confirmed duplicates do not rewrite data. Index maintenance adds billable row writes; inspect D1 meta.rows_written for actual account usage.

The current D1 Free limits include 50 queries per invocation and 100 bound parameters per statement. Tests count the actual database calls for the 630-row example, including access/preview/publication, below 50. Preview also enforces a maximum of 32 staging statements before any writes, leaving room for access, planning, publication and error cleanup. D1 pricing allows 100,000 written rows/day account-wide, shared with live tracking and index maintenance. This importer does not reserve the account's remaining allowance; schedule small imports with headroom rather than treating that limit as a per-site allowance. It does not increment tracked-event quotas.

Workers Free has a 10 ms CPU limit. Parsing/ZIP expansion uses CPU, and local test wall time is not production CPU measurement. Production CPU at the largest accepted size is unverified; use smaller exports if the runtime interrupts processing. Such a request cannot publish partial history. Automated resumable large-history/API imports are not implemented.

HTTP reference

These browser-session endpoints require a site admin or owner and reject API bearer credentials; CSRF checks apply to mutations.

MethodPathBody
POST/api/sites/:id/imports/ga4/previewRaw CSV (text/csv) or ZIP (application/zip), no multipart
POST/api/sites/:id/imports/ga4Identical body plus X-Import-Preview from preview
GET/api/sites/:id/importsShared history, limits, timezone; provider is ga4 or plausible
DELETE/api/sites/:id/imports/:importIdRemoves exactly that site's import

New publication returns 201, an existing digest 200, invalid input 400/415, resource limits 413, stale previews/duplicates within an upload/overlap 409. Inaccessible sites return 404; workspace viewers receive 403 for import management/history.

Data API: later option

Google's Data API v1 and properties.runReport can request an explicit date dimension, report dimensions and metric names. It returns JSON dimension/metric headers and row values; it is not the UI CSV download. A later connector could produce these same aggregates with pagination, compatibility checks and resumable imports.

The existing Search Console OAuth integration requests a different permission. GA4 access would add https://www.googleapis.com/auth/analytics.readonly and new consent. Google's scope list and sensitive-scope verification guidance require checking app verification before a public release. No Google scopes, OAuth tokens or Search Console behavior were changed for CSV import.