dotfiles/dot_agents/skills/cloudflare/references/graphql-api/api.md

GraphQL Analytics API Reference

Query Root

The schema has a single entry point: Query.viewer. Mutations are not supported.

{
  cost       # uint64 -- query cost (returned in response)
  viewer {
    budget   # uint64 -- remaining budget
    zones(filter: { zoneTag: "..." }) { ... }
    accounts(filter: { accountTag: "..." }) { ... }
  }
}

Aggregation Fields

Aggregated dataset nodes (*Groups) return these field categories. Not every node has all — use introspection to check.

count

Total events in the group. Available on *Groups nodes but not on raw *Adaptive nodes (e.g., workersInvocationsAdaptive — use sum { requests } instead).

sum

Cumulative metrics. Fields vary by dataset:

# HTTP requests
sum { edgeResponseBytes edgeRequestBytes visits edgeTimeToFirstByteMs originResponseDurationMs }

# Workers invocations
sum { requests errors subrequests cpuTimeUs wallTime duration responseBodySize clientDisconnects requestDuration }

quantiles

Percentile distributions (on datasets like workersInvocationsAdaptive). Available percentiles: P25, P50, P75, P90, P95, P99, P999 for cpuTime, wallTime, requestDuration, duration, responseBodySize.

quantiles { cpuTimeP50 cpuTimeP99 wallTimeP50 wallTimeP99 }

ratio, avg, uniq, confidence

ratio { status4xx status5xx }      # float64 (0 to 1) -- HTTP datasets only
avg { sampleInterval }              # useful for understanding sampling resolution
uniq { uniques }                    # unique IP count -- rollup datasets (*1hGroups, *1dGroups) only
confidence(level: 0.95) {           # Adaptive datasets only; works on count and sum fields
  count { estimate lower upper sampleSize }
}

Dimensions

Dimensions are fields you can group by via the dimensions sub-selection.

Time Dimensions

Dimension	Granularity
date	Day
datetime	Exact timestamp
datetimeMinute	1 minute
datetimeFiveMinutes	5 minutes
datetimeFifteenMinutes	15 minutes
datetimeHour	1 hour

Workers datasets also support datetimeSixHours.

HTTP Request Dimensions (httpRequestsAdaptiveGroups)

83 dimensions available. Key ones:

Dimension	Description
clientCountryName	Country of origin
clientRequestHTTPHost	Requested hostname
clientRequestHTTPMethodName	HTTP method
clientRequestPath	URI path
edgeResponseStatus	Edge HTTP status code
cacheStatus	Cache status (hit, miss, dynamic, etc.)
coloCode	Cloudflare datacenter IATA code
clientIP / clientAsn	Client IP address / ASN
botScore / botManagementDecision	Bot management score (0-99) / verdict
wafAttackScore / securityAction	WAF score / firewall action taken
ja3Hash / ja4	TLS fingerprints
sampleInterval	ABR sample interval

Workers Dimensions (workersInvocationsAdaptive)

scriptName, scriptTag, scriptVersion, environmentName, status, usageModel, coloCode, dispatchNamespaceName, isDispatcher

Firewall Dimensions (firewallEventsAdaptive)

action, source, ruleId, clientCountryName, clientIP, clientAsn, userAgent

Filtering

Scope Filters

zones(filter: { zoneTag: "ZONE_ID" })           # up to 10 zones
zones(filter: { zoneTag_in: ["Z1", "Z2"] })
accounts(filter: { accountTag: "ACCOUNT_ID" })   # exactly 1 account

Dataset Filters

Always include a time range filter. Multiple filters at the same level are implicitly AND-ed.

httpRequestsAdaptiveGroups(
  filter: { datetime_gt: "2025-01-01T00:00:00Z", datetime_lt: "2025-01-02T00:00:00Z", clientCountryName: "US" }
  limit: 1000
)

Filter Operators

Operator	Meaning	Example
(none)	equals	clientCountryName: "US"
_gt / _lt	greater / less than	datetime_gt: "..."
_geq / _leq	greater/less or equal	datetime_geq: "..."
_neq	not equal	cacheStatus_neq: "hit"
_in / _notin	in / not in list	clientCountryName_in: ["US", "GB"]
_like / _notlike	SQL LIKE with %	clientRequestPath_like: "/api/%"
_has / _hasall / _hasany	array contains	botDetectionIds_has: "abc"

_notin and _notlike are in the schema but not in official docs. Confirmed via introspection.

Boolean Operators (AND / OR)

# Explicit AND
filter: { AND: [{ datetime_gt: "..." }, { datetime_lt: "..." }, { clientCountryName: "US" }] }

# Explicit OR
filter: { datetime_gt: "...", OR: [{ edgeResponseStatus: 403 }, { edgeResponseStatus: 429 }] }

Pagination & Sorting

No cursor-based pagination. Use limit, orderBy, and filter-based offsets:

# First page
httpRequestsAdaptiveGroups(filter: { datetime_gt: "..." }, limit: 100, orderBy: [datetime_ASC])

# Next page: filter by last seen value from previous page
httpRequestsAdaptiveGroups(filter: { datetime_gt: "2025-01-01T01:35:00Z" }, limit: 100, orderBy: [datetime_ASC])

Sort with orderBy: [field_ASC] or [field_DESC]. Multiple sort fields supported.

Settings Node

Query per-node limits and availability:

viewer { zones(filter: { zoneTag: "..." }) { settings {
  httpRequestsAdaptiveGroups { enabled maxDuration maxNumberOfFields maxPageSize notOlderThan }
} } }

See Also

• README.md - Overview, decision tree, dataset index
• configuration.md - Authentication, client setup, introspection queries
• patterns.md - Common query patterns (time-series, top-N, per-product)
• gotchas.md - Rate limits, sampling, troubleshooting