Add GraphQL Analytics API reference skill#25
Merged
dmmulroy merged 2 commits intocloudflare:mainfrom Feb 26, 2026
Merged
Conversation
New reference covering Cloudflare's GraphQL Analytics API — the single
endpoint for querying analytics across all Cloudflare products (HTTP,
Workers, DNS, Firewall, R2, KV, D1, AI, and 70+ other datasets).
New files:
- references/graphql-api/README.md — Overview, decision tree, dataset
index, naming conventions, reading order
- references/graphql-api/api.md — Query structure, aggregation fields
(sum/avg/quantiles/count/ratio/uniq/confidence), dimensions, filtering
operators, pagination, sorting, introspection, settings node
- references/graphql-api/configuration.md — Auth (API tokens), client
setup (curl, TypeScript, Python, Workers), GraphQL Explorer, schema
introspection, finding zone/account IDs
- references/graphql-api/patterns.md — 15+ ready-to-use query patterns:
time-series, top-N, Workers performance, firewall events, DNS, cache
analytics, R2/KV/D1 storage, AI inference, multi-dataset dashboards
- references/graphql-api/gotchas.md — Rate limits, ABR sampling caveats,
common errors (with solutions), plan-based availability, datetime
handling, performance tips
Modified files:
- SKILL.md — Added analytics/metrics decision tree, added GraphQL API
entry to Developer Tools product index
- analytics-engine/README.md — Added See Also cross-links to graphql-api
and observability references
- api/README.md — Added See Also cross-link to graphql-api reference
- observability/README.md — Added See Also cross-link to graphql-api
- web-analytics/README.md — Added reciprocal cross-link to graphql-api
Testing:
- Thorough human review (read-through of each file)
- Two comprehensive AI reviews using parallel subagents for factual
accuracy, completeness, and style — followed by a validation pass that
filtered false positives. Caught and fixed 8 issues:
- Settings node query was structurally invalid (missing dataset nesting)
- R2 query pattern used nonexistent count field (only sum/dimensions/
confidence exist on r2OperationsAdaptiveGroups)
- Worker example in configuration.md was missing datetime_lt upper
bound, contradicting the skill's own best practice
- Confidence interval example included undocumented isValid field
- Rate limit described as flat 300/5min; corrected to cost-based
default 300, max 320
- Separator convention (-- vs -) mismatched peer references; fixed
across all 5 files
- web-analytics/ was missing reciprocal cross-link
- _notin/_notlike operators initially removed as undocumented, then
re-added after schema introspection confirmed they exist (with note)
- 20 GraphQL queries executed against a live Cloudflare account covering:
zone-scoped (HTTP time-series, top-N countries/paths/errors, firewall
events/blocks, DNS volume, cache breakdown, multi-dataset dashboard,
confidence intervals, daily rollups with uniq, _like filter, _notin
filter, aliases) and account-scoped (Workers overview/error-rate with
quantiles, KV operations, R2 operations, settings node, cost/budget).
19/20 passed on first attempt; the 1 failure (R2 count) was fixed.
Contributor
Author
|
@elithrar @whoiskatrin PR to add GraphQL API reference files to skills. |
Collaborator
|
Generally looks good to me - could you have opencode take a pass at trying to get each file down to <=200 lines 🙏 a little over is fine |
Contributor
Author
|
@dmmulroy Good call-out, thanks. This is fixed now.
|
dmmulroy
approved these changes
Feb 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
graphql-api/reference skill (5 files, ~1750 lines) covering the Cloudflare GraphQL Analytics API — query structure, filtering, aggregation, auth/client setup, 15+ query patterns, and common gotchasSKILL.mdwith an analytics decision tree and product index entryanalytics-engine/,api/,observability/, andweb-analytics/READMEsNew files
graphql-api/README.mdgraphql-api/api.mdgraphql-api/configuration.mdgraphql-api/patterns.mdgraphql-api/gotchas.mdValidation
countfield doesn't exist) — corrected before commit_notin,_notlike) confirmed via schema introspection and noted accordinglyReview process
After initial generation, all 5 files went through three layers of review:
1. AI parallel review: Three independent subagents reviewed the files simultaneously, each with a different focus area:
2. AI validation pass: A final subagent reviewed all findings from step 1, reading each cited
file:lineto classify issues as Confirmed, Disputed, or Acknowledged. Only confirmed findings were actioned. 8 issues were found and fixed, including incorrect field names, missing operator documentation, and style inconsistencies.3. Human review: All files were read and reviewed by a human before commit.
The two-phase AI review process is documented here.