Skip to content
Skills Library
Data & analytics · Analysis

cloudflare-analytics

/cloudflare-analytics

Queries Cloudflare traffic and usage analytics via the GraphQL Analytics API — per-hostname request/visitor/bandwidth breakdowns, cached-vs-uncached request counts, Workers and Pages Functions invocation metrics, Web Analytics/RUM. Use when asked how much traffic a site, app, or subdomain gets, which services are actually used, or when writing or debugging a Cloudflare GraphQL query, or when such a query returns errors or empty results.

Licence
MIT
Last repository change
19.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
3
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 19.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/cf-host-traffic.sh, scripts/cf-limits.sh, scripts/cf-query.sh

What it does and when to use it

Queries Cloudflare traffic and usage analytics via the GraphQL Analytics API — per-hostname request/visitor/bandwidth breakdowns, cached-vs-uncached request counts, Workers and Pages Functions invocation metrics, Web Analytics/RUM. Use when asked how much traffic a site, app, or subdomain gets, which services are actually used, or when writing or debugging a Cloudflare GraphQL query, or when such a query returns errors or empty results.

Original author description

Queries Cloudflare traffic and usage analytics via the GraphQL Analytics API — per-hostname request/visitor/bandwidth breakdowns, cached-vs-uncached request counts, Workers and Pages Functions invocation metrics, Web Analytics/RUM. Use when asked how much traffic a site, app, or subdomain gets, which services are actually used, or when writing or debugging a Cloudflare GraphQL query, or when such a query returns errors or empty results.

How it works

  1. Setup
  2. Workflow
  3. Non-obvious behavior
  4. Interpreting output
  5. Proactive triggers
Original SKILL.md headings · 94 lines, 619 words
SKILL.md preview
---
name: cloudflare-analytics
description: Queries Cloudflare traffic and usage analytics via the GraphQL Analytics API — per-hostname request/visitor/bandwidth breakdowns, cached-vs-uncached request counts, Workers and Pages Functions invocation metrics, Web Analytics/RUM. Use when asked how much traffic a site, app, or subdomain gets, which services are actually used, or when writing or debugging a Cloudflare GraphQL query, or when such a query returns errors or empty results.
---

# Cloudflare Analytics

Cloudflare's MCP servers do **not** expose traffic analytics — the observability
server covers Workers Logs only (and only when a Worker sets `[observability]`
in its wrangler config), and Radar is public internet-wide data unrelated to any
one account. Per-hostname numbers come from the GraphQL Analytics API, which
these scripts wrap.

## Setup

All scripts need `CLOUDFLARE_API_TOKEN`. Create at dash.cloudflare.com → My
Profile → API Tokens → Custom token with `Zone > Analytics > Read`,
`Zone > Zone > Read`, and `Account > Account Analytics > Read`.

**Never let the user paste the token into the conversation** — it lands in the
transcript permanently. Ask them to run the command themselves (in Claude Code,
prefixed with `!`), which returns only the output. If a token does end up in the
transcript, say so plainly and tell them to rotate it.

## Workflow

**1. Probe limits first.** Plan entitlements decide what is answerable, and they
are not derivable from the docs — the published API capability is not the same
as a given zone's grant.

```bash
scripts/cf-limits.sh <zone-name>
```

Returns `maxDuration` (widest single window) and `notOlderThan` (retention) per
dataset. These are independent: 8-day retention with a 1-day max window means
eight separate queries, not one.

**2. Pick the dataset by whether you need a per-hostname breakdown.**
`clientRequestHTTPHost` exists only on `httpRequestsAdaptiveGroups`, which is
the most range-restricted dataset. That tension drives most decisions here —
see [references/datasets.md](references/datasets.md).

**3. Run.**

```bash
scripts/cf-host-traffic.sh <zone> [YYYY-MM-DD]  # per-hostname table, 24h window
scripts/cf-query.sh <query-file> '<vars-json>'  # arbitrary query
```

`cf-query.sh` accepts `-` to read the query from stdin, prints raw JSON, and
exits non-zero on GraphQL errors.

## Non-obvious behavior

**Errors arrive with HTTP 200.** A failed query returns status 200 with an
`errors` array. Always inspect `body.errors`; both scripts do.

**Numbers may be estimates.** `…Adaptive` datasets sample adaptively by volume,
so a quiet host returns exact counts while a busy one is extrapolated — in the
same table. Always select `avg { sampleInterval }` and report a value > 1 as an
estimate, not a measurement. Extrapolation mechanics: see
[references/datasets.md](references/datasets.md#sampling).

**Empty results are rarely a permissions problem.** Missing scopes return 403.
Empty usually means the beacon isn't installed (RUM), the Worker has no
`[observability]` block (Workers Logs), or the window fell outside retention.

**Per-hostname history beyond `notOlderThan` does not exist and cannot be
reconstructed.** With 8-day retention, "per-app traffic last month" is not
answerable — say so instead of silently substituting zone-wide totals from
`httpRequests1dGroups`, which measure something different.

## Interpreting output

- `VISITS = 0` on API-serving hosts is correct — visits approximate page loads,
  and those hosts serve API calls, not pages.
- Hostnames with an explicit `:port` or a trailing dot are bot/scanner noise;
  `cf-host-traffic.sh` excludes them from the table and totals them in a footer.
- Edge request counts and RUM page views will never match. Edge counts bots,
  assets, and API calls, and treats each unique IP as a visit.
- A zone often hosts more than the services under discussion — confirm which
  hostnames the user actually means before summarizing "app traffic".

## Proactive triggers

- User asks for per-hostname traffic older than the dataset's retention → state
  the limit and offer zone-wide `httpRequests1dGroups` totals as the alternative,
  naming the difference.
- A query fails with "time range wider than" → chunk into `maxDuration`-sized
  windows instead of retrying.
- `avg sampleInterval` > 2 on a reported number → label it an estimate in the
  summary, not a count.
- User pastes an API token into the chat → flag it immediately and advise
  rotation.
- Asked for "visitors" on a host that serves an API → explain visits ≈ page
  loads and suggest request counts instead.
Files in this package (5)
  • SKILL.md 5 KB
  • references/datasets.md 6 KB
  • scripts/cf-host-traffic.sh 3 KB
  • scripts/cf-limits.sh 2 KB
  • scripts/cf-query.sh 1 KB

Versions

The database has no other skills named cloudflare-analytics.

Database snapshot: 13.11.2026 · package version 8a697f1441c3 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100google-analytics
    Query Google Analytics 4 (GA4) reports via the Analytics Data API v1 and list properties via the Admin API. Use when the user mentions Google Analytics, GA4, website traffic / sessions / users, top pages or sources, conversions, or a realtime report.
  • 100cloudflare-deployment
    Deploy and manage Cloudflare Workers, Pages, KV, R2, and D1 using wrangler CLI or MCP server. Use when working with Cloudflare services, serverless functions, or edge deployments.
  • 95Cloudflare
    Deploy Cloudflare Workers/Pages. USE WHEN Cloudflare, worker, deploy, Pages, MCP server. SkillSearch('cloudflare') for docs.
  • 100cloudflare-workers-observability
    Cloudflare Workers observability with logging, Analytics Engine, Tail Workers, metrics, and alerting. Use for monitoring, debugging, tracing, or encountering log parsing, metric aggregation, alert configuration errors.
  • 100arize-graphql-analytics
    Query and analyze data from the Arize platform using GraphQL, or help build/validate GraphQL queries and mutations. Use when users want to explore spaces, models, monitors, datasets, any Arize platform data, OR when they need help writing, formatting, or debugging GraphQL…
  • 100cloudflare-deploy
    Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.