Analytics Engine

Record custom analytics events from a Worker using Workers Analytics Engine. The experiment_events dataset is auto-created on first write - no manual dashboard setup required.

API ReferenceCopy Anchor Link

POST /trackCopy Anchor Link

Writes a named event with an optional numeric value and tag to the Analytics Engine dataset.

Example RequestCopy Anchor Link

curl -X POST "https://your-worker.workers.dev/track" \
  -H "Content-Type: application/json" \
  -d '{"event":"page_view","value":1,"tag":"homepage"}'

Success ResponseCopy Anchor Link

ok boolean

Always true on success

event string

The event name that was recorded

value number

The numeric value that was written

{
  "ok": true,
  "event": "page_view",
  "value": 1
}

Error ResponseCopy Anchor Link

{
  "error": "Missing or invalid field: event (required non-empty string, max 100 characters)",
  "code": "INVALID_EVENT"
}

Error CodesCopy Anchor Link

• 400 - Invalid JSON body (INVALID_BODY)
• 400 - Missing or invalid event (INVALID_EVENT)

Use CasesCopy Anchor Link

• Emit custom metrics from edge Workers without a third-party analytics SDK
• Track feature usage, clicks, or conversions with named events and tags
• Learn Analytics Engine writeDataPoint in a minimal stateless API
• Prototype observability pipelines before wiring dashboards and SQL queries

LimitationsCopy Anchor Link

• Writes datapoints only; no query or dashboard API in this experiment
• No sampling, aggregation, or retention configuration
• Requires an Analytics Engine binding in wrangler.json

Use in your projectCopy Anchor Link

import { MAX_EVENT_LENGTH } from "../constants/defaults";export function validateEvent(input: unknown): string | null {  if (typeof input !== "string") return null;  const trimmed = input.trim();  if (!trimmed) return null;  if (trimmed.length > MAX_EVENT_LENGTH) return null;  return trimmed;}export function normalizeValue(input: unknown): number {  if (typeof input === "number" && Number.isFinite(input)) {    return input;  }  return 1;}export function normalizeTag(input: unknown): string {  if (typeof input !== "string") return "";  return input.trim();}

DeploymentCopy Anchor Link

curl -X POST "https://your-worker.workers.dev/track" \
  -H "Content-Type: application/json" \
  -d '{"event":"page_view","value":1,"tag":"homepage"}'

Local DevelopmentCopy Anchor Link

cd apps/experiments/analytics-engine
npm install
npm run dev

Test locally:

curl -X POST "http://localhost:8787/track" \
  -H "Content-Type: application/json" \
  -d '{"event":"demo_click","value":1,"tag":"local"}'

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• Workers Analytics Engine - experiment_events dataset via ANALYTICS binding