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.
- Author
- Goodsmileduck ↗
- Repository
- goodsmileduck-claude-registry ↗
- Licence
- MIT
- Last repository change
- 19.07.2026
Assessment and security
- Files in this package
- 5
- Scripts
- 3
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 19.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 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
- Setup
- Workflow
- Non-obvious behavior
- Interpreting output
- Proactive triggers
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.