- Oct 14, 2026
- 4 min read
Querying Cloudflare Web Analytics with the GraphQL API
Cloudflare Web Analytics is the cookieless analytics I use on every site. The dashboard showed one domain with 3 visits a day across five subdomains, which seemed low even for me. Before writing a single query, I had to fix the data.
Step 0: check the script is actually there
Web Analytics needs a small script (the “beacon”) on each page. Look for it in the HTML that’s actually served, and in a real browser, since some setups only inject it for certain visitors:
curl -s https://www.example.com/ | grep -c 'cloudflareinsights.com/beacon'
On my sites: 0 everywhere except one blog. The difference was in the dashboard (Analytics & Logs → Web Analytics → the site → Manage site):
| Setup | What it does | What I saw |
|---|---|---|
| Enable (automatic) | Cloudflare injects the script at the edge | Not injected on my Pages-hosted sites |
| Enable, excluding EU visitors | Same, skipped for EU visitors | Hides most of an EU audience |
| Enable with JS snippet installation | You add the script yourself | What the working blog used |
I switched to the snippet and added it to each site’s shared layout:
<script type="module" src="https://static.cloudflareinsights.com/beacon.min.js"
data-cf-beacon='{"token": "<site token>"}'></script>
The token isn’t secret: it’s in every page’s HTML. If you have a Content
Security Policy, allow https://static.cloudflareinsights.com in
script-src and https://cloudflareinsights.com in connect-src. I checked
each site in a browser for blocked requests, with the report request
intercepted so the test didn’t add fake visits. On an installable web app,
check that the service worker ignores cross-origin requests, so it neither
caches nor blocks the beacon.
The API: one GraphQL endpoint
Everything Cloudflare’s dashboards show comes from a GraphQL API:
POST https://api.cloudflare.com/client/v4/graphql
Authorization: Bearer <token>
For Web Analytics the token needs Account → Account Analytics → Read. For a long-running job (my homelab’s weekly summary) I create a dedicated read-only token for exactly that.
Web Analytics data lives under the account, in the dataset
rumPageloadEventsAdaptiveGroups (RUM = real user monitoring). One query can
ask for several groupings at once with aliases:
query ($account: String!, $start: Date!, $end: Date!) {
viewer {
accounts(filter: { accountTag: $account }) {
byHost: rumPageloadEventsAdaptiveGroups(
limit: 30
filter: { date_geq: $start, date_leq: $end }
orderBy: [sum_visits_DESC]
) {
count # page views
sum { visits } # visits
dimensions { requestHost }
}
topPages: rumPageloadEventsAdaptiveGroups(
limit: 15
filter: { date_geq: $start, date_leq: $end }
orderBy: [count_DESC]
) {
count
dimensions { requestHost requestPath }
}
referrers: rumPageloadEventsAdaptiveGroups(
limit: 15
filter: { date_geq: $start, date_leq: $end }
orderBy: [count_DESC]
) {
count
dimensions { refererHost }
}
countries: rumPageloadEventsAdaptiveGroups(
limit: 8
filter: { date_geq: $start, date_leq: $end }
orderBy: [count_DESC]
) {
count
dimensions { countryName }
}
}
}
}
Sent with curl, variables included:
curl -s https://api.cloudflare.com/client/v4/graphql \
-H "Authorization: Bearer $CF_ANALYTICS_TOKEN" -H "Content-Type: application/json" \
-d "$(jq -n --arg q "$(cat query.graphql)" --arg a "$ACCOUNT_ID" \
--arg s "$(date -d '-6 days' +%F)" --arg e "$(date +%F)" \
'{query:$q, variables:{account:$a, start:$s, end:$e}}')"
Other dimensions worth knowing: date (for daily series), deviceType,
userAgentBrowser. Filters compose: requestHost_in: [...],
requestHost_neq: "...".
What the numbers said
A week of data across my properties:
| Host | Visits |
|---|---|
| The self-hosting blog | 2,594 |
| Main site | 33 (from the day the beacon went in) |
| Product site + its web app | 19 + 15 |
The query made two things visible that the dashboard’s headline number hid:
- Most of the big number is probably bots. 2,605 page views had no referrer, and the top countries were the US (1,170), Singapore (987) and China (497), against 26 from Poland, where I live and write. Crawlers that run JavaScript count as visits. Google’s Chrome UX Report had no real-user data for that blog at all, which points the same way.
- An old duplicate address was still in the numbers. Visits on the
blog’s
pages.devhostname looked like a missing redirect. Filtering bydateshowed every one of them happened before I added the redirect on 4 October, and none since. Always check the date range before “fixing” something.
Takeaways
- Check that the beacon is in the page before trusting a dashboard. Automatic injection silently did nothing on my Pages sites.
- One GraphQL endpoint, one read-only token:
rumPageloadEventsAdaptiveGroupsgives visits, pages, referrers and countries. - Group by
datebefore concluding anything. - Visits aren’t people. No referrer plus unexpected countries usually means crawlers. Compare with Search Console clicks and real signups before celebrating a number.