1# Cloudflare GraphQL Analytics API
2 
3Query analytics data across all Cloudflare products via a single GraphQL endpoint. Covers HTTP requests, Workers metrics, DNS, Firewall events, Network Analytics, and 70+ other datasets.
4 
5## Overview
6 
7- **Single endpoint** for all analytics: `https://api.cloudflare.com/client/v4/graphql`
8- **1,400+ schema types** spanning every Cloudflare product
9- **Two scopes**: zone-level (per-domain) and account-level (cross-domain)
10- **Adaptive sampling** on high-traffic datasets with confidence intervals
11- **No mutations** - read-only analytics (the Mutation type is a stub)
12- **Cost-based rate limiting** - default 300 queries per 5 minutes per user (max 320, varies by query cost)
13 
14## Quick Decision Tree
15 
16```
17Need analytics data from Cloudflare?
18├─ HTTP traffic (requests, bandwidth, cache) → httpRequestsAdaptiveGroups (zone or account)
19├─ Workers performance (CPU, wall time, errors) → workersInvocationsAdaptive (account)
20├─ Firewall/WAF events → firewallEventsAdaptive / firewallEventsAdaptiveGroups (zone or account)
21├─ DNS query analytics → dnsAnalyticsAdaptive / dnsAnalyticsAdaptiveGroups (zone or account)
22├─ Network layer (DDoS, Magic Transit) → *NetworkAnalyticsAdaptiveGroups (account)
23├─ Storage (R2, KV, D1, DO) → r2OperationsAdaptiveGroups / kvOperationsAdaptiveGroups / etc. (account)
24├─ AI (Workers AI, AI Gateway) → aiInferenceAdaptive / aiGatewayRequestsAdaptiveGroups (account)
25├─ Load Balancing → loadBalancingRequestsAdaptiveGroups (zone)
26├─ Custom high-cardinality metrics → Workers Analytics Engine (see ../analytics-engine/)
27└─ Need raw logs, not aggregates → Logpush (see Cloudflare docs)
28```
29 
30## Core Concepts
31 
32| Concept | Description |
33|---------|-------------|
34| **Endpoint** | `POST https://api.cloudflare.com/client/v4/graphql` |
35| **Explorer** | [graphql.cloudflare.com](https://graphql.cloudflare.com/) - interactive query builder |
36| **Viewer** | Root query object: `viewer { zones(...) { ... } }` or `viewer { accounts(...) { ... } }` |
37| **Dataset (Node)** | A queryable table under a zone or account (e.g., `httpRequestsAdaptiveGroups`) |
38| **Dimensions** | Fields to group by (time buckets, country, status code, script name, etc.) |
39| **Metrics** | Aggregation fields: `count`, `sum { ... }`, `avg { ... }`, `quantiles { ... }`, `ratio { ... }` |
40| **Filter** | Input object constraining results by time range, dimensions, etc. |
41| **Limit** | Maximum rows returned per dataset node (required, max varies by dataset) |
42| **OrderBy** | Enum-based sorting: `[field_ASC]` or `[field_DESC]` |
43| **Adaptive Sampling** | Nodes with `Adaptive` in the name use ABR sampling; results are statistically representative |
44 
45## Query Structure
46 
47Every query follows this pattern:
48 
49```graphql
50{
51  viewer {
52    # Zone-scoped
53    zones(filter: { zoneTag: "ZONE_ID" }) {
54      datasetName(
55        filter: { datetime_gt: "...", datetime_lt: "..." }
56        limit: 1000
57        orderBy: [datetimeFiveMinutes_DESC]
58      ) {
59        count
60        dimensions { ... }
61        sum { ... }
62      }
63    }
64    # Account-scoped
65    accounts(filter: { accountTag: "ACCOUNT_ID" }) {
66      datasetName(filter: { ... }, limit: 100) {
67        count
68        dimensions { ... }
69        sum { ... }
70      }
71    }
72  }
73}
74```
75 
76## Dataset Naming Convention
77 
78Dataset names follow a consistent pattern visible in the schema:
79 
80| Pattern | Meaning | Example |
81|---------|---------|---------|
82| `*Adaptive` | Raw rows with adaptive sampling; some (e.g., `workersInvocationsAdaptive`) also support aggregation fields (`sum`, `quantiles`, `avg`) | `httpRequestsAdaptive`, `workersInvocationsAdaptive` |
83| `*AdaptiveGroups` | Aggregated data with adaptive sampling | `httpRequestsAdaptiveGroups` |
84| `*1hGroups` | Hourly rollups (pre-aggregated) | `httpRequests1hGroups` |
85| `*1dGroups` | Daily rollups (pre-aggregated) | `httpRequests1dGroups` |
86| `*1mGroups` | Minutely rollups | `httpRequests1mGroups` |
87| `Zone*` prefix | Zone-scoped dataset | `ZoneHttpRequestsAdaptiveGroups` |
88| `Account*` prefix | Account-scoped dataset | `AccountWorkersInvocationsAdaptive` |
89 
90**Prefer `*AdaptiveGroups` nodes** for most use cases - they support flexible time grouping via dimension fields (`datetimeFiveMinutes`, `datetimeHour`, etc.) and are the most commonly used.
91 
92## Key Datasets by Product
93 
94### Zone-Scoped (per-domain)
95 
96| Dataset | Description |
97|---------|-------------|
98| `httpRequestsAdaptiveGroups` | HTTP traffic: requests, bytes, cache status, bot scores, WAF scores |
99| `httpRequests1hGroups` / `1dGroups` / `1mGroups` | Pre-aggregated HTTP rollups (hourly/daily/minutely) |
100| `firewallEventsAdaptiveGroups` | WAF, rate limiting, bot management, firewall rule events |
101| `dnsAnalyticsAdaptiveGroups` | DNS query volumes, response codes, query types |
102| `loadBalancingRequestsAdaptiveGroups` | Load Balancer origin request metrics |
103| `pageShieldReportsAdaptiveGroups` | Page Shield CSP reports |
104 
105### Account-Scoped (cross-domain)
106 
107| Dataset | Description |
108|---------|-------------|
109| `workersInvocationsAdaptive` | Workers: requests, errors, CPU time, wall time, subrequests |
110| `durableObjectsInvocationsAdaptiveGroups` | DO invocations |
111| `durableObjectsStorageGroups` / `durableObjectsPeriodicGroups` | DO storage and periodic metrics |
112| `d1AnalyticsAdaptiveGroups` / `d1QueriesAdaptiveGroups` | D1 database analytics |
113| `r2OperationsAdaptiveGroups` / `r2StorageAdaptiveGroups` | R2 operations and storage |
114| `kvOperationsAdaptiveGroups` / `kvStorageAdaptiveGroups` | KV operations and storage |
115| `aiInferenceAdaptiveGroups` | Workers AI inference metrics |
116| `aiGatewayRequestsAdaptiveGroups` | AI Gateway request analytics |
117| `pagesFunctionsInvocationsAdaptiveGroups` | Pages Functions metrics |
118| `magicTransitNetworkAnalyticsAdaptiveGroups` | Magic Transit packet/byte analytics |
119| `spectrumNetworkAnalyticsAdaptiveGroups` | Spectrum TCP/UDP analytics |
120| `gatewayL7RequestsAdaptiveGroups` | Zero Trust Gateway HTTP metrics |
121| `gatewayResolverQueriesAdaptiveGroups` | Zero Trust Gateway DNS metrics |
122 
123## Reading Order
124 
125| Task | Start Here | Then Read |
126|------|------------|-----------|
127| **First query** | [configuration.md](configuration.md) (auth) -> this README (structure) | [api.md](api.md) |
128| **Build a dashboard** | [patterns.md](patterns.md) (time-series, top-N) | [api.md](api.md) (aggregation fields) |
129| **Debug query issues** | [gotchas.md](gotchas.md) | [api.md](api.md) (filtering) |
130| **Understand sampling** | [gotchas.md](gotchas.md) (sampling section) | [api.md](api.md) (confidence intervals) |
131| **Product-specific metrics** | [patterns.md](patterns.md) (per-product examples) | [api.md](api.md) (dataset reference) |
132 
133## In This Reference
134 
135- **[api.md](api.md)** - Query structure, aggregation fields (sum/avg/quantiles/count), filtering operators, dimensions, dataset details
136- **[configuration.md](configuration.md)** - Authentication, API tokens, client setup (curl, JS, Python), introspection
137- **[patterns.md](patterns.md)** - Common queries: time-series, top-N, Workers metrics, HTTP analytics, firewall events, multi-zone
138- **[gotchas.md](gotchas.md)** - Rate limits, sampling caveats, query cost, common errors, plan-based limits
139 
140## See Also
141 
142- [GraphQL Analytics API Docs](https://developers.cloudflare.com/analytics/graphql-api/)
143- [GraphQL API Explorer](https://graphql.cloudflare.com/)
144- [Observability Reference](../observability/) - Workers Logs, Tail Workers, console logging
145- [Analytics Engine Reference](../analytics-engine/) - Custom high-cardinality analytics via Workers
146- [Web Analytics Reference](../web-analytics/) - Client-side (RUM) analytics
147- [API Reference](../api/) - REST API, SDKs, authentication basics
148