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 Reference

POST /track

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

Example Request

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

Success Response

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 Response

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

Error Codes

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

Use Cases

• 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

Limitations

• 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

Deployment

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

Local Development

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 Used

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