Cloudflare GraphQL Analytics API
Query 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.
Overview
- Single endpoint for all analytics:
https://api.cloudflare.com/client/v4/graphql - 1,400+ schema types spanning every Cloudflare product
- Two scopes: zone-level (per-domain) and account-level (cross-domain)
- Adaptive sampling on high-traffic datasets with confidence intervals
- No mutations - read-only analytics (the Mutation type is a stub)
- Cost-based rate limiting - default 300 queries per 5 minutes per user (max 320, varies by query cost)
Quick Decision Tree
Need analytics data from Cloudflare?
├─ HTTP traffic (requests, bandwidth, cache) → httpRequestsAdaptiveGroups (zone or account)
├─ Workers performance (CPU, wall time, errors) → workersInvocationsAdaptive (account)
├─ Firewall/WAF events → firewallEventsAdaptive / firewallEventsAdaptiveGroups (zone or account)
├─ DNS query analytics → dnsAnalyticsAdaptive / dnsAnalyticsAdaptiveGroups (zone or account)
├─ Network layer (DDoS, Magic Transit) → *NetworkAnalyticsAdaptiveGroups (account)
├─ Storage (R2, KV, D1, DO) → r2OperationsAdaptiveGroups / kvOperationsAdaptiveGroups / etc. (account)
├─ AI (Workers AI, AI Gateway) → aiInferenceAdaptive / aiGatewayRequestsAdaptiveGroups (account)
├─ Load Balancing → loadBalancingRequestsAdaptiveGroups (zone)
├─ Custom high-cardinality metrics → Workers Analytics Engine (see ../analytics-engine/)
└─ Need raw logs, not aggregates → Logpush (see Cloudflare docs)
Core Concepts
| Concept | Description |
|---|
| Endpoint | POST https://api.cloudflare.com/client/v4/graphql |
| Explorer | graphql.cloudflare.com - interactive query builder |
| Viewer | Root query object: viewer { zones(...) { ... } } or viewer { accounts(...) { ... } } |
| Dataset (Node) | A queryable table under a zone or account (e.g., httpRequestsAdaptiveGroups) |
| Dimensions | Fields to group by (time buckets, country, status code, script name, etc.) |
| Metrics | Aggregation fields: count, sum { ... }, avg { ... }, quantiles { ... }, ratio { ... } |
| Filter | Input object constraining results by time range, dimensions, etc. |
| Limit | Maximum rows returned per dataset node (required, max varies by dataset) |
| OrderBy | Enum-based sorting: [field_ASC] or [field_DESC] |
| Adaptive Sampling | Nodes with Adaptive in the name use ABR sampling; results are statistically representative |
Query Structure
Every query follows this pattern:
{
viewer {
# Zone-scoped
zones(filter: { zoneTag: "ZONE_ID" }) {
datasetName(
filter: { datetime_gt: "...", datetime_lt: "..." }
limit: 1000
orderBy: [datetimeFiveMinutes_DESC]
) {
count
dimensions { ... }
sum { ... }
}
}
# Account-scoped
accounts(filter: { accountTag: "ACCOUNT_ID" }) {
datasetName(filter: { ... }, limit: 100) {
count
dimensions { ... }
sum { ... }
}
}
}
}
Dataset Naming Convention
Dataset names follow a consistent pattern visible in the schema:
| Pattern | Meaning | Example |
|---|
*Adaptive | Raw rows with adaptive sampling; some (e.g., workersInvocationsAdaptive) also support aggregation fields (sum, quantiles, avg) | httpRequestsAdaptive, workersInvocationsAdaptive |
*AdaptiveGroups | Aggregated data with adaptive sampling | httpRequestsAdaptiveGroups |
*1hGroups | Hourly rollups (pre-aggregated) | httpRequests1hGroups |
*1dGroups | Daily rollups (pre-aggregated) | httpRequests1dGroups |
*1mGroups | Minutely rollups | httpRequests1mGroups |
Zone* prefix | Zone-scoped dataset | ZoneHttpRequestsAdaptiveGroups |
Account* prefix | Account-scoped dataset | AccountWorkersInvocationsAdaptive |
Prefer *AdaptiveGroups nodes for most use cases - they support flexible time grouping via dimension fields (datetimeFiveMinutes, datetimeHour, etc.) and are the most commonly used.
Key Datasets by Product
Zone-Scoped (per-domain)
| Dataset | Description |
|---|
httpRequestsAdaptiveGroups | HTTP traffic: requests, bytes, cache status, bot scores, WAF scores |
httpRequests1hGroups / 1dGroups / 1mGroups | Pre-aggregated HTTP rollups (hourly/daily/minutely) |
firewallEventsAdaptiveGroups | WAF, rate limiting, bot management, firewall rule events |
dnsAnalyticsAdaptiveGroups | DNS query volumes, response codes, query types |
loadBalancingRequestsAdaptiveGroups | Load Balancer origin request metrics |
pageShieldReportsAdaptiveGroups | Page Shield CSP reports |
Account-Scoped (cross-domain)
| Dataset | Description |
|---|
workersInvocationsAdaptive | Workers: requests, errors, CPU time, wall time, subrequests |
durableObjectsInvocationsAdaptiveGroups | DO invocations |
durableObjectsStorageGroups / durableObjectsPeriodicGroups | DO storage and periodic metrics |
d1AnalyticsAdaptiveGroups / d1QueriesAdaptiveGroups | D1 database analytics |
r2OperationsAdaptiveGroups / r2StorageAdaptiveGroups | R2 operations and storage |
kvOperationsAdaptiveGroups / kvStorageAdaptiveGroups | KV operations and storage |
aiInferenceAdaptiveGroups | Workers AI inference metrics |
aiGatewayRequestsAdaptiveGroups | AI Gateway request analytics |
pagesFunctionsInvocationsAdaptiveGroups | Pages Functions metrics |
magicTransitNetworkAnalyticsAdaptiveGroups | Magic Transit packet/byte analytics |
spectrumNetworkAnalyticsAdaptiveGroups | Spectrum TCP/UDP analytics |
gatewayL7RequestsAdaptiveGroups | Zero Trust Gateway HTTP metrics |
gatewayResolverQueriesAdaptiveGroups | Zero Trust Gateway DNS metrics |
Reading Order
In This Reference
- api.md - Query structure, aggregation fields (sum/avg/quantiles/count), filtering operators, dimensions, dataset details
- configuration.md - Authentication, API tokens, client setup (curl, JS, Python), introspection
- patterns.md - Common queries: time-series, top-N, Workers metrics, HTTP analytics, firewall events, multi-zone
- gotchas.md - Rate limits, sampling caveats, query cost, common errors, plan-based limits
See Also