Analytics

Type: Core module
Build impact: Adds small, independently loaded browser runtimes
Modules: Traffic, Attribution, Events and conversions

Analytics is the product surface for understanding traffic and outcomes. Its modules remain technically independent: campaign forwarding must still work if traffic reporting or an external analytics provider is unavailable.

Module	Purpose	Reference
Traffic	Cookieless visits, page views, referrers, Core Web Vitals, and AI-assistant referrals	This page
Events and conversions	Record validated first-party funnel events and report their sources	Events and conversions

Configuration

Field	Purpose	Exposure
`beacon_token`	Identifies the site to the browser beacon	Included in the published HTML
`site_tag`	Identifies the property when the portal reads reports	Server-side only

You normally leave both empty. Enabling Analytics creates a Cloudflare Web Analytics site for the site’s address and fills both fields. site_tag is always derived from the token, so you never need to enter it. Redeploy the site after the token changes so published pages carry the beacon.

First-party conversion events also require a public portal or forms-service URL and the platform signing secret; without both, builds omit the event endpoint while traffic measurement continues to work.

Which Cloudflare account is used

Analytics lives in, and Insights reads from, the Cloudflare account that hosts the site:

Site publishing	Cloudflare account
Customer publishing	The account of the site’s Hosting Group. Default uses the Organization’s Cloudflare connection.
Managed hosting (Cloud)	The installation’s account, which also hosts the site.
Self-hosted installation	The account set in `CLOUDFLARE_ACCOUNT_ID` with `CLOUDFLARE_API_TOKEN`.

For customer publishing, Typeroll never falls back to another account. If the Hosting Group’s connection is missing or lacks permission, Analytics reports why instead of creating the site elsewhere. read_app and update_app return the account as setup.account; its owner is organization or installation.

Permissions for customer publishing

Task	OAuth connection (scope)	API token permission
Create the Web Analytics site	Account Settings (edit), `account-settings.write`	Account → Account Settings → Edit
Find the site of a pasted token	Included in every connection (Account Settings read)	Account → Account Settings → Read
Read reports for Insights	Account Analytics (read), `account-analytics.read`	Account → Account Analytics → Read

When the installation requests these permissions during onboarding, Connect Cloudflare includes them, and enabling Analytics on a new Site creates its Web Analytics site at once, without another approval. A connection made earlier gets them with one Approve update on its Cloudflare card in Publishing, per Cloudflare account and not per Site (see Cloudflare permissions). The analytics_cloudflare_access_required setup then names that card in next_step and links it as settings_url; return and enable Analytics again.

On an installation that does not request them during onboarding, select Approve Analytics access on Analytics in the site’s Settings → Core modules. An owner or admin of the Organization signs in to Cloudflare again for the site’s Hosting Group account and approves the permissions; the existing account, sites and media stay connected. Return to the module and select Save settings, or call update_app again. Later reconnects keep the approval. A connection made with an API token needs the token permissions above instead: edit the token in Cloudflare, then enable Analytics again.

Approving permissions turns Analytics on for no Site. Measurement is chosen per Site.

Read a Site’s insights

get_site_insights returns the last 7, 30 or 90 days (days) for one Site: traffic, visits referred by AI assistants, and conversion events grouped by event, destination, source and campaign. Traffic comes from Cloudflare Web Analytics in the account the beacon belongs to; conversions come from validated click events. The traffic status is ok, no_data for a linked site without visits, or a reason such as app_disabled, not_configured, no_site_tag, connection_required, access_required, account_mismatch or provider_error, with code, message, next_step and settings_url. Conversion data can be present even when traffic is unavailable.

Choose Sites across the Organization

Publishing → Analytics lists the Organization’s Sites with Analytics on or off and each one’s setup. Owners and admins select the Sites that should measure traffic and save; only Sites whose choice changed are updated, each in the same way as enabling the module on that Site. The tab also says when a Hosting Group’s Cloudflare account still needs its permission update. Agents use list_organization_analytics (GET /api/v1/organization/analytics) and set_organization_analytics (POST /api/v1/organization/analytics with {"sites": [{"site_id": "…", "enabled": true}]}, at most 50 Sites) with an organization API key. The answer has one result per Site: ready, action_required with code, message, next_step and settings_url, disabled, or error when nothing changed for that Site. Publish each Site you turned on to add the beacon to its pages.

If you prefer not to grant Account Settings (edit), create a Web Analytics site yourself in the same Cloudflare account (Analytics & Logs → Web Analytics, without automatic setup) and paste its token as beacon_token. Typeroll finds its site_tag in that account. Insights still needs Account Analytics (read).

A token from a different Cloudflare account is refused for customer publishing, because Insights could never read it. Managed and self-hosted sites still accept such a token for beacon-only measurement; their reports are then only available in the Cloudflare dashboard, and setup says so. When several Organizations share one Cloudflare account, each Web Analytics site belongs to the Organization that created or first linked it.

Setup results and failure messages

update_app answers 200 with setup.status: "ready" when the beacon is set up. When no beacon could be set up, Analytics is still saved as enabled and the call answers 409 with a code, a message and details.next_step (details.saved is true). Fix the cause and enable Analytics again; the call is safe to repeat. A pasted token that cannot be used is refused with 409 and details.saved: false. read_app and the module card show the same setup.

`code`	Meaning and next step
`analytics_cloudflare_access_required`	The hosting account’s connection may not create sites or read reports. Approve the permission update, or add the token permissions.
`analytics_cloudflare_connection_required`	The site’s Hosting Group has no usable Cloudflare connection. Connect or check it in Account → Publishing.
`analytics_host_required`	The site has no address yet. Set a website host, or a site address base for its Hosting Group.
`analytics_provider_error`	Cloudflare did not complete the request. The message names the HTTP status and Cloudflare error codes. Try again.
`analytics_provider_rate_limited`	Cloudflare rate-limited the request. Wait a minute and try again.
`analytics_token_not_in_account`	The pasted token is not in the hosting account. Paste a token from that account, or clear the fields to create one.
`analytics_site_tag_mismatch`	The supplied `site_tag` does not belong to the token. Omit `site_tag`.
`analytics_site_owned_by_other_organization`	Another Organization sharing the account owns that Web Analytics site. Clear the fields to create one for this site.
`analytics_account_mismatch`	The saved site is in another account than the one hosting the site, for example after leaving managed hosting.
`analytics_account_not_configured`	Managed or self-hosted: the installation has no Cloudflare account configured. Paste a token, or configure the account.
`analytics_not_provisioned`	Enabled earlier without a token. Enable Analytics again to create the Web Analytics site.

To replace the saved Web Analytics site with a new one in the hosting account, send {"enabled": true, "config": {"beacon_token": "", "site_tag": ""}}, then redeploy the site.

Traffic insights

The Traffic module reports visits and page views over 7, 30, or 90 days, top referrers, Core Web Vitals, and visits referred by AI assistants. AI referrals are ordinary referral traffic at the collection layer; Insights classifies their referring hosts so each assistant can be reported separately.

This complements the llms.txt, semantic HTML, and structured data Typeroll publishes to help search engines and assistants understand the site. See SEO and indexing.

Runtime and privacy

The beacon is emitted during the static build. Cloudflare Web Analytics is cookieless and intended for aggregate traffic measurement, so the beacon loads directly and is not held by the cookie banner. Typeroll configures it with its token only and sets no cookies or storage for it. Confirm the legal requirements that apply to your site and jurisdiction before relying on a particular consent treatment.

Conversion events follow the site’s consent decision. Core does not store campaign cookies or rewrite outbound links. Installed apps may add those behaviors under their own documented consent policy.

Insights states

Insights reads reports from the same account as the beacon and distinguishes missing setup, missing access and a property with no data yet, so an empty report is never ambiguous. Every state other than ok, no_data and app_disabled includes a reason with code, message, next_step and, where relevant, settings_url. The response also names the account it read.

State	Meaning
`app_disabled`	Analytics is not active for the site
`not_configured`	Managed or self-hosted: the installation has no Cloudflare account configured
`no_site_tag`	Analytics is active but not linked to a Web Analytics site; the reason says why
`connection_required`	Customer publishing: the site’s Hosting Group has no usable Cloudflare connection
`access_required`	The hosting account’s connection may not read reports (Account Analytics read)
`account_mismatch`	The linked Web Analytics site is not in the account that hosts the site
`provider_error`	Cloudflare did not return reports; try again
`no_data`	The property is linked but has no traffic for the selected period
`ok`	Traffic totals and breakdowns are available

The same surface reports first-party conversion events separately. Conversion reporting can continue to show data when Cloudflare traffic reporting is temporarily unavailable.