1# Analytics Engine API Reference
2 
3## Writing Data
4 
5### `writeDataPoint()`
6 
7Fire-and-forget (returns `void`, not Promise). Writes happen asynchronously.
8 
9```typescript
10interface AnalyticsEngineDataPoint {
11  blobs?: string[];      // Up to 20 strings (dimensions), 16KB each
12  doubles?: number[];    // Up to 20 numbers (metrics)
13  indexes?: string[];    // 1 indexed string for high-cardinality filtering
14}
15 
16env.ANALYTICS.writeDataPoint({
17  blobs: ["/api/users", "GET", "200"],
18  doubles: [145.2, 1],  // latency_ms, count
19  indexes: ["customer_abc123"]
20});
21```
22 
23**Behaviors:** No await needed, no error thrown (check tail logs), auto-sampled at high volumes, auto-timestamped.
24 
25**Blob vs Index:** Blob for GROUP BY (<100k unique), Index for filter-only (millions unique).
26 
27### Full Example
28 
29```typescript
30export default {
31  async fetch(request: Request, env: Env): Promise<Response> {
32    const start = Date.now();
33    const url = new URL(request.url);
34    try {
35      const response = await handleRequest(request);
36      env.ANALYTICS.writeDataPoint({
37        blobs: [url.pathname, request.method, response.status.toString()],
38        doubles: [Date.now() - start, 1],
39        indexes: [request.headers.get("x-api-key") || "anonymous"]
40      });
41      return response;
42    } catch (error) {
43      env.ANALYTICS.writeDataPoint({
44        blobs: [url.pathname, request.method, "500"],
45        doubles: [Date.now() - start, 1, 0],
46      });
47      throw error;
48    }
49  }
50};
51```
52 
53## SQL API (External Only)
54 
55```bash
56curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql \
57  -H "Authorization: Bearer $TOKEN" \
58  -d "SELECT blob1 AS endpoint, COUNT(*) AS requests FROM dataset WHERE timestamp >= NOW() - INTERVAL '1' HOUR GROUP BY blob1"
59```
60 
61### Column References
62 
63```sql
64-- blob1..blob20, double1..double20, index1, timestamp
65SELECT blob1 AS endpoint, SUM(double1) AS latency, COUNT(*) AS requests
66FROM my_dataset
67WHERE index1 = 'customer_123' AND timestamp >= NOW() - INTERVAL '7' DAY
68GROUP BY blob1
69HAVING COUNT(*) > 100
70ORDER BY requests DESC LIMIT 100
71```
72 
73**Aggregations:** `SUM()`, `AVG()`, `COUNT()`, `MIN()`, `MAX()`, `quantile(0.95)()`
74 
75**Time ranges:** `NOW() - INTERVAL '1' HOUR`, `BETWEEN '2026-01-01' AND '2026-01-31'`
76 
77### Query Examples
78 
79```sql
80-- Top endpoints
81SELECT blob1, COUNT(*) AS requests, AVG(double1) AS avg_latency
82FROM api_requests WHERE timestamp >= NOW() - INTERVAL '24' HOUR
83GROUP BY blob1 ORDER BY requests DESC LIMIT 20
84 
85-- Error rate
86SELECT blob1, COUNT(*) AS total,
87  SUM(CASE WHEN blob3 LIKE '5%' THEN 1 ELSE 0 END) AS errors
88FROM api_requests WHERE timestamp >= NOW() - INTERVAL '1' HOUR
89GROUP BY blob1 HAVING total > 50
90 
91-- P95 latency
92SELECT blob1, quantile(0.95)(double1) AS p95
93FROM api_requests GROUP BY blob1
94```
95 
96## Response Format
97 
98```json
99{"data": [{"endpoint": "/api/users", "requests": 1523}], "rows": 2}
100```
101 
102## Limits
103 
104| Resource | Limit |
105|----------|-------|
106| Blobs/Doubles per point | 20 each |
107| Indexes per point | 1 |
108| Blob/Index size | 16KB |
109| Data retention | 90 days |
110| Query timeout | 30s |
111 
112**Critical:** High write volumes (>1M/min) trigger automatic sampling.
113