---
description: Connect existing Cloudflare Web Analytics collection and understand Studio's time ranges, metrics, caching, and failures.
---

# Web Analytics

Administrators can view public-site traffic in Studio's Analytics page.
The connection is optional and disabled by default. Studio reads existing
Cloudflare Web Analytics data; it does not install a collection script or
change the site's Cloudflare configuration.

## Connect a Site

1. Set the public site URL and time zone in **Site Settings → General**.
2. In **Site Settings → Analytics**, open **Select site in Cloudflare**,
   choose the site, and paste that browser URL into **Web Analytics URL**.
3. Check the extracted Account ID and Site Tag. Use direct entry if needed.
4. Use **Create API Token in Cloudflare** to preselect
   **Account Analytics → Read**, then enter a token for that account.
5. Test the connection, enable Analytics, and save.

The saved target is restricted to the selected Site Tag and the public site's
exact hostname. `example.com` and `www.example.com` are different targets.
Only the IDs are taken from the pasted dashboard URL; its filters and time
range do not configure Studio's query. Site Tag is not the collection script's
token.

The API token is encrypted with an Analytics-specific key derived from
`STUDIO_AUTH_SECRET`. It is not returned by reads or included in Preview Data.
Leave the field blank to keep the token, replace it by entering a new one,
or disable Analytics before removing it.

## Connection Test and Data Collection

A connection test can use unsaved input. It confirms API access and checks
whether the last 24 hours contain data. A successful query with no traffic
does not prove the collection script is installed or collecting correctly.

## Ranges and Metrics

The default range is **Last 24 hours**. Choices run from 30 minutes to 30 days.
The interval ends at the latest five-minute boundary; its daily breakdown uses
the site's saved time zone, including applicable daylight-saving transitions.
The first and last days can contain only part of a calendar day.

| Metric | Meaning |
| --- | --- |
| Page views | Page views reported for the selected site and hostname |
| Visits | Arrivals from another site or a direct link; not unique people |
| Daily trend | Activity within each day's portion of the selected interval |
| Top URLs and referrers | The ten highest page-view totals over the whole selected interval |

Top lists are not produced by adding each day's top ten. Empty referrers are
shown as Direct / unknown. Studio uses Cloudflare's returned estimates without
multiplying them again by a sampling rate. Read Cloudflare's
[metric definitions](https://developers.cloudflare.com/web-analytics/data-metrics/high-level-metrics/)
when comparing these values with another analytics product.

## Caching and Failures

Studio queries `rumPageloadEventsAdaptiveGroups` from the Worker. Daily
aggregation requests are batched rather than sent as one sequential HTTP call
for every day. Results may be sampled.

Successful results are cached for up to five minutes. The cache distinguishes
connection revision, hostname, time zone, and period. Connection or target
changes prevent reuse of the old result. The screen shows the last fetch time
and does not poll automatically.

A KV failure falls back to a direct query; a failed cache write does not discard
a successful response. Authentication failures, query limits, and temporary
service failures appear as errors, not a fabricated zero-visit result. Try a
shorter period when the account's query limits prevent a longer range.