1# GraphQL Analytics API Configuration
2 
3## Authentication
4 
5### API Token (Recommended)
6 
7| Permission | Scope | Use Case |
8|------------|-------|----------|
9| **Account Analytics: Read** | Account-wide | Workers, R2, KV, D1, DO, AI, Network Analytics |
10| **Zone Analytics: Read** | Per-zone | HTTP requests, Firewall, DNS, Load Balancing |
11| **All zones - Analytics: Read** | All zones | Multi-zone HTTP/Firewall/DNS queries |
12 
13Create tokens at: [dash.cloudflare.com > Account API Tokens](https://dash.cloudflare.com/?to=/:account/api-tokens)
14 
15```bash
16# Verify token
17curl -s https://api.cloudflare.com/client/v4/graphql \
18  -H "Authorization: Bearer $CF_API_TOKEN" \
19  -H "Content-Type: application/json" \
20  --data '{"query":"{ viewer { zones(filter: {zoneTag: \"ZONE_ID\"}) { httpRequestsAdaptiveGroups(limit: 1, filter: {datetime_gt: \"2025-01-01T00:00:00Z\"}) { count } } } }"}'
21```
22 
23### API Key + Email (Legacy)
24 
25Not recommended. Use `X-Auth-Email` + `X-Auth-Key` headers instead of `Authorization: Bearer`.
26 
27## Client Setup
28 
29### curl
30 
31```bash
32curl -s https://api.cloudflare.com/client/v4/graphql \
33  -H "Authorization: Bearer $CF_API_TOKEN" \
34  -H "Content-Type: application/json" \
35  --data '{
36    "query": "query($zoneTag: string!, $start: Time!, $end: Time!) { viewer { zones(filter: {zoneTag: $zoneTag}) { httpRequestsAdaptiveGroups(filter: {datetime_gt: $start, datetime_lt: $end}, limit: 10, orderBy: [datetimeFiveMinutes_DESC]) { count dimensions { datetimeFiveMinutes } } } } }",
37    "variables": { "zoneTag": "ZONE_ID", "start": "2025-01-01T00:00:00Z", "end": "2025-01-02T00:00:00Z" }
38  }' | jq .
39```
40 
41### TypeScript / JavaScript
42 
43```typescript
44const GRAPHQL_ENDPOINT = "https://api.cloudflare.com/client/v4/graphql";
45 
46async function queryGraphQL<T>(query: string, variables: Record<string, unknown> = {}): Promise<T> {
47  const response = await fetch(GRAPHQL_ENDPOINT, {
48    method: "POST",
49    headers: { Authorization: `Bearer ${process.env.CF_API_TOKEN}`, "Content-Type": "application/json" },
50    body: JSON.stringify({ query, variables }),
51  });
52  if (!response.ok) throw new Error(`HTTP ${response.status}: ${response.statusText}`);
53  const json = await response.json() as { data: T | null; errors?: { message: string }[] };
54  if (json.errors?.length) throw new Error(json.errors.map((e) => e.message).join("; "));
55  return json.data!;
56}
57```
58 
59### Python
60 
61```python
62import requests, os
63 
64def query_graphql(query: str, variables: dict = None) -> dict:
65    r = requests.post("https://api.cloudflare.com/client/v4/graphql",
66        headers={"Authorization": f"Bearer {os.environ['CF_API_TOKEN']}", "Content-Type": "application/json"},
67        json={"query": query, "variables": variables or {}})
68    r.raise_for_status()
69    result = r.json()
70    if result.get("errors"):
71        raise Exception("; ".join(e["message"] for e in result["errors"]))
72    return result["data"]
73```
74 
75### From a Cloudflare Worker
76 
77Store the API token as a secret (`CF_API_TOKEN`). Use standard `fetch` to POST to `https://api.cloudflare.com/client/v4/graphql` with the same JSON body format as above. Always check `response.errors` — GraphQL returns 200 even on query failures.
78 
79## GraphQL API Explorer
80 
81Interactive explorer at [graphql.cloudflare.com](https://graphql.cloudflare.com/) — provides schema docs, autocomplete, variable panel, and shareable queries. Authenticates via your Cloudflare dashboard session.
82 
83## Schema Introspection
84 
85```graphql
86# List zone-scoped datasets
87{ __type(name: "zone") { fields { name description } } }
88 
89# List account-scoped datasets
90{ __type(name: "account") { fields { name description } } }
91 
92# Discover dimensions for a dataset
93{ __type(name: "ZoneHttpRequestsAdaptiveGroupsDimensions") {
94  fields { name type { name kind } }
95} }
96 
97# Discover filter operators for a dataset
98{ __type(name: "ZoneHttpRequestsAdaptiveGroupsFilter_InputObject") {
99  inputFields { name type { name kind } }
100} }
101```
102 
103## Finding Your Zone and Account IDs
104 
105- **Zone ID**: Dashboard > select zone > Overview (right sidebar), or via API
106- **Account ID**: Dashboard > Account Home URL, or via API
107 
108```bash
109curl -s https://api.cloudflare.com/client/v4/zones -H "Authorization: Bearer $CF_API_TOKEN" | jq '.result[] | {name, id}'
110curl -s https://api.cloudflare.com/client/v4/accounts -H "Authorization: Bearer $CF_API_TOKEN" | jq '.result[] | {name, id}'
111```
112 
113## See Also
114 
115- [README.md](README.md) - Overview, decision tree, dataset index
116- [api.md](api.md) - Query structure, aggregation fields, filtering operators
117- [patterns.md](patterns.md) - Common query patterns (time-series, top-N, per-product)
118- [gotchas.md](gotchas.md) - Rate limits, sampling, troubleshooting
119