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

Workers datasets also support datetimeSixHours.

HTTP Request Dimensions (httpRequestsAdaptiveGroups)

83 dimensions available. Key ones:

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

_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