Cloudflare REST API End-of-Life: Complete GraphQL Migration Checklist

Cloudflare has been steadily migrating its analytics and reporting endpoints from the legacy REST API (v4) to its GraphQL Analytics API. While the core CRUD operations for DNS records, zones, and configuration remain on REST (and will for the foreseeable future), the analytics and reporting endpoints that many monitoring tools depend on are being sunset. Several legacy analytics REST endpoints were officially deprecated in late 2025, with full removal planned throughout 2026.

This guide provides a complete migration checklist for teams that need to move from deprecated REST analytics endpoints to Cloudflare's GraphQL API, along with example queries and testing strategies.

What Is Being Deprecated (and What Is Not)

It is critical to understand that Cloudflare is not deprecating its entire REST API. The v4 REST API for zone management, DNS records, WAF rules, Workers, and configuration endpoints remains fully supported. What is being deprecated are specific analytics and reporting endpoints that have GraphQL equivalents:

Deprecated REST Endpoint	GraphQL Replacement	Removal Date
`/zones/:id/analytics/dashboard`	`httpRequestsAdaptiveGroups`	Q2 2026
`/zones/:id/analytics/colos`	`httpRequestsAdaptiveGroups` with colo filter	Q2 2026
`/zones/:id/dns_analytics/report`	`dnsAnalyticsAdaptiveGroups`	Q3 2026
`/zones/:id/firewall/events`	`firewallEventsAdaptive`	Q2 2026
`/user/load_balancers/pools/:id/health`	`loadBalancingRequestsAdaptiveGroups`	Q3 2026

Important: If you are only using Cloudflare's REST API for DNS record management, zone configuration, or Workers deployment, no migration is needed. Those endpoints are stable and actively developed.

Architectural Differences: REST vs GraphQL

The shift from REST to GraphQL is not just a syntax change. It fundamentally changes how you query Cloudflare data:

Single endpoint: All GraphQL queries go to https://api.cloudflare.com/client/v4/graphql. No more memorizing dozens of REST paths.
Flexible field selection: Request only the fields you need. REST endpoints returned fixed response shapes with 50+ fields whether you needed them or not.
Cross-resource queries: A single GraphQL query can pull HTTP analytics, firewall events, and DNS stats in one request. REST required separate calls.
Time-series native: GraphQL datasets are designed for time-series analytics with built-in grouping by datetime, datetimeHour, or datetimeMinute.
Consistent filtering: All datasets use the same filter syntax. REST endpoints had inconsistent query parameter formats.

Example Queries for Common Use Cases

HTTP Traffic Analytics (Replacing /analytics/dashboard)

query {
  viewer {
    zones(filter: {zoneTag: "YOUR_ZONE_ID"}) {
      httpRequestsAdaptiveGroups(
        filter: {
          datetime_gt: "2026-03-08T00:00:00Z"
          datetime_lt: "2026-03-09T00:00:00Z"
        }
        limit: 1000
        orderBy: [datetime_ASC]
      ) {
        dimensions {
          datetime
          clientCountryName
          clientRequestHTTPHost
        }
        sum {
          requests
          bytes
          cachedRequests
          cachedBytes
          threats
          pageViews
        }
        avg {
          sampleInterval
        }
      }
    }
  }
}

DNS Analytics (Replacing /dns_analytics/report)

query {
  viewer {
    zones(filter: {zoneTag: "YOUR_ZONE_ID"}) {
      dnsAnalyticsAdaptiveGroups(
        filter: {
          datetime_gt: "2026-03-01T00:00:00Z"
          datetime_lt: "2026-03-09T00:00:00Z"
        }
        limit: 100
        orderBy: [sum_queryCount_DESC]
      ) {
        dimensions {
          queryName
          queryType
          responseCode
        }
        sum {
          queryCount
        }
      }
    }
  }
}

Firewall Events (Replacing /firewall/events)

query {
  viewer {
    zones(filter: {zoneTag: "YOUR_ZONE_ID"}) {
      firewallEventsAdaptive(
        filter: {
          datetime_gt: "2026-03-08T00:00:00Z"
          action: "block"
        }
        limit: 50
        orderBy: [datetime_DESC]
      ) {
        action
        clientIP
        clientCountryName
        datetime
        source
        userAgent
        ruleId
        matchIndex
      }
    }
  }
}

Migration Checklist

Use this checklist to track your migration progress across your infrastructure:

Phase 1: Discovery and Audit

Inventory all services making Cloudflare REST analytics API calls (search codebases for /analytics/, /dns_analytics/, /firewall/events)
Document the specific fields each service consumes from REST responses
Identify third-party tools (Datadog, Grafana, Terraform) that use deprecated endpoints
Check if third-party integrations already support Cloudflare GraphQL (Grafana's Cloudflare plugin does since v0.3.0)
Map each REST endpoint to its GraphQL dataset equivalent using the table above

Phase 2: Build GraphQL Queries

Set up authentication: same API token works for both REST and GraphQL, but ensure your token has the Analytics:Read permission
Use the GraphQL introspection endpoint or Cloudflare's GraphQL Explorer to discover available datasets and fields
Write equivalent GraphQL queries for each REST call identified in Phase 1
Handle pagination: GraphQL uses limit and cursor-based pagination, not page numbers
Implement proper error handling for GraphQL-specific errors (partial results, field-level errors)

Phase 3: Testing and Validation

Run REST and GraphQL queries in parallel for at least 7 days and compare outputs
Validate numeric accuracy: sums, counts, and averages should match within sampling tolerances (Cloudflare's adaptive bitrate sampling means exact numbers may differ by up to 5%)
Test edge cases: empty date ranges, zones with no traffic, queries that return zero results
Load test GraphQL queries at production volume to verify performance and rate limit behavior
Verify dashboard/reporting tools render GraphQL data correctly

Phase 4: Cutover

Deploy GraphQL-based code to production behind a feature flag
Monitor error rates and response times for 48 hours
Remove REST analytics code paths
Update monitoring alerts that reference deprecated endpoint response formats
Document new query patterns in team runbooks

Rate Limits and Performance Considerations

Cloudflare's GraphQL API has different rate limiting than REST:

Query complexity limit: Each query has a computed complexity score. Queries requesting many fields across large time ranges consume more complexity budget.
Rate limit: 300 GraphQL requests per 5-minute window per API token (vs. 1,200 for REST). However, since a single GraphQL query can replace multiple REST calls, effective throughput is usually higher.
Response size: GraphQL responses are typically 60-80% smaller than equivalent REST responses because you only receive requested fields.
Timeout: Complex queries that scan large time ranges may timeout at 10 seconds. Break large queries into smaller time windows (hourly instead of daily for high-traffic zones).

Common Migration Mistakes

Querying all fields: Developers often start by requesting every available field "just in case." This bloats response sizes and can hit complexity limits. Only request fields your application actually uses.
Ignoring sampling: Cloudflare's adaptive datasets use sampling for high-volume zones. The avg { sampleInterval } field tells you the sampling ratio. A sample interval of 10 means roughly 1 in 10 events were sampled, and counts are already extrapolated.
Forgetting timezone handling: All GraphQL timestamps are UTC. If your REST integration assumed a different timezone, your time-bucketed reports will shift.
Not handling partial errors: GraphQL can return 200 OK with both data and errors in the response. Always check the errors array even on successful HTTP responses.

The migration is straightforward for teams with a small number of analytics integrations. For larger organizations running Cloudflare across hundreds of zones with custom monitoring dashboards, budget two to four weeks for the full migration cycle. Start now — the Q2 2026 removal dates for HTTP and firewall analytics are less than three months away.