• 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):

SetupWhat it doesWhat I saw
Enable (automatic)Cloudflare injects the script at the edgeNot injected on my Pages-hosted sites
Enable, excluding EU visitorsSame, skipped for EU visitorsHides most of an EU audience
Enable with JS snippet installationYou add the script yourselfWhat 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:

HostVisits
The self-hosting blog2,594
Main site33 (from the day the beacon went in)
Product site + its web app19 + 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.dev hostname looked like a missing redirect. Filtering by date showed 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: rumPageloadEventsAdaptiveGroups gives visits, pages, referrers and countries.
  • Group by date before 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.