1# GraphQL Analytics API Reference
2 
3## Query Root
4 
5The schema has a single entry point: `Query.viewer`. Mutations are not supported.
6 
7```graphql
8{
9  cost       # uint64 -- query cost (returned in response)
10  viewer {
11    budget   # uint64 -- remaining budget
12    zones(filter: { zoneTag: "..." }) { ... }
13    accounts(filter: { accountTag: "..." }) { ... }
14  }
15}
16```
17 
18## Aggregation Fields
19 
20Aggregated dataset nodes (`*Groups`) return these field categories. Not every node has all — use introspection to check.
21 
22### count
23 
24Total events in the group. Available on `*Groups` nodes but **not** on raw `*Adaptive` nodes (e.g., `workersInvocationsAdaptive` — use `sum { requests }` instead).
25 
26### sum
27 
28Cumulative metrics. Fields vary by dataset:
29 
30```graphql
31# HTTP requests
32sum { edgeResponseBytes edgeRequestBytes visits edgeTimeToFirstByteMs originResponseDurationMs }
33 
34# Workers invocations
35sum { requests errors subrequests cpuTimeUs wallTime duration responseBodySize clientDisconnects requestDuration }
36```
37 
38### quantiles
39 
40Percentile distributions (on datasets like `workersInvocationsAdaptive`). Available percentiles: P25, P50, P75, P90, P95, P99, P999 for `cpuTime`, `wallTime`, `requestDuration`, `duration`, `responseBodySize`.
41 
42```graphql
43quantiles { cpuTimeP50 cpuTimeP99 wallTimeP50 wallTimeP99 }
44```
45 
46### ratio, avg, uniq, confidence
47 
48```graphql
49ratio { status4xx status5xx }      # float64 (0 to 1) -- HTTP datasets only
50avg { sampleInterval }              # useful for understanding sampling resolution
51uniq { uniques }                    # unique IP count -- rollup datasets (*1hGroups, *1dGroups) only
52confidence(level: 0.95) {           # Adaptive datasets only; works on count and sum fields
53  count { estimate lower upper sampleSize }
54}
55```
56 
57## Dimensions
58 
59Dimensions are fields you can group by via the `dimensions` sub-selection.
60 
61### Time Dimensions
62 
63| Dimension | Granularity |
64|-----------|------------|
65| `date` | Day |
66| `datetime` | Exact timestamp |
67| `datetimeMinute` | 1 minute |
68| `datetimeFiveMinutes` | 5 minutes |
69| `datetimeFifteenMinutes` | 15 minutes |
70| `datetimeHour` | 1 hour |
71 
72Workers datasets also support `datetimeSixHours`.
73 
74### HTTP Request Dimensions (httpRequestsAdaptiveGroups)
75 
7683 dimensions available. Key ones:
77 
78| Dimension | Description |
79|-----------|-------------|
80| `clientCountryName` | Country of origin |
81| `clientRequestHTTPHost` | Requested hostname |
82| `clientRequestHTTPMethodName` | HTTP method |
83| `clientRequestPath` | URI path |
84| `edgeResponseStatus` | Edge HTTP status code |
85| `cacheStatus` | Cache status (hit, miss, dynamic, etc.) |
86| `coloCode` | Cloudflare datacenter IATA code |
87| `clientIP` / `clientAsn` | Client IP address / ASN |
88| `botScore` / `botManagementDecision` | Bot management score (0-99) / verdict |
89| `wafAttackScore` / `securityAction` | WAF score / firewall action taken |
90| `ja3Hash` / `ja4` | TLS fingerprints |
91| `sampleInterval` | ABR sample interval |
92 
93### Workers Dimensions (workersInvocationsAdaptive)
94 
95`scriptName`, `scriptTag`, `scriptVersion`, `environmentName`, `status`, `usageModel`, `coloCode`, `dispatchNamespaceName`, `isDispatcher`
96 
97### Firewall Dimensions (firewallEventsAdaptive)
98 
99`action`, `source`, `ruleId`, `clientCountryName`, `clientIP`, `clientAsn`, `userAgent`
100 
101## Filtering
102 
103### Scope Filters
104 
105```graphql
106zones(filter: { zoneTag: "ZONE_ID" })           # up to 10 zones
107zones(filter: { zoneTag_in: ["Z1", "Z2"] })
108accounts(filter: { accountTag: "ACCOUNT_ID" })   # exactly 1 account
109```
110 
111### Dataset Filters
112 
113**Always include a time range filter.** Multiple filters at the same level are implicitly AND-ed.
114 
115```graphql
116httpRequestsAdaptiveGroups(
117  filter: { datetime_gt: "2025-01-01T00:00:00Z", datetime_lt: "2025-01-02T00:00:00Z", clientCountryName: "US" }
118  limit: 1000
119)
120```
121 
122### Filter Operators
123 
124| Operator | Meaning | Example |
125|----------|---------|---------|
126| (none) | equals | `clientCountryName: "US"` |
127| `_gt` / `_lt` | greater / less than | `datetime_gt: "..."` |
128| `_geq` / `_leq` | greater/less or equal | `datetime_geq: "..."` |
129| `_neq` | not equal | `cacheStatus_neq: "hit"` |
130| `_in` / `_notin` | in / not in list | `clientCountryName_in: ["US", "GB"]` |
131| `_like` / `_notlike` | SQL LIKE with `%` | `clientRequestPath_like: "/api/%"` |
132| `_has` / `_hasall` / `_hasany` | array contains | `botDetectionIds_has: "abc"` |
133 
134> `_notin` and `_notlike` are in the schema but not in official docs. Confirmed via introspection.
135 
136### Boolean Operators (AND / OR)
137 
138```graphql
139# Explicit AND
140filter: { AND: [{ datetime_gt: "..." }, { datetime_lt: "..." }, { clientCountryName: "US" }] }
141 
142# Explicit OR
143filter: { datetime_gt: "...", OR: [{ edgeResponseStatus: 403 }, { edgeResponseStatus: 429 }] }
144```
145 
146## Pagination & Sorting
147 
148No cursor-based pagination. Use `limit`, `orderBy`, and filter-based offsets:
149 
150```graphql
151# First page
152httpRequestsAdaptiveGroups(filter: { datetime_gt: "..." }, limit: 100, orderBy: [datetime_ASC])
153 
154# Next page: filter by last seen value from previous page
155httpRequestsAdaptiveGroups(filter: { datetime_gt: "2025-01-01T01:35:00Z" }, limit: 100, orderBy: [datetime_ASC])
156```
157 
158Sort with `orderBy: [field_ASC]` or `[field_DESC]`. Multiple sort fields supported.
159 
160## Settings Node
161 
162Query per-node limits and availability:
163 
164```graphql
165viewer { zones(filter: { zoneTag: "..." }) { settings {
166  httpRequestsAdaptiveGroups { enabled maxDuration maxNumberOfFields maxPageSize notOlderThan }
167} } }
168```
169 
170## See Also
171 
172- [README.md](README.md) - Overview, decision tree, dataset index
173- [configuration.md](configuration.md) - Authentication, client setup, introspection queries
174- [patterns.md](patterns.md) - Common query patterns (time-series, top-N, per-product)
175- [gotchas.md](gotchas.md) - Rate limits, sampling, troubleshooting
176