Documented steps

Add the dataset binding in wrangler.toml: `[[analytics_engine_datasets]]` with `binding = "<BINDING_NAME>"` and `dataset = "<DATASET_NAME>"`. In wrangler.jsonc: `"analytics_engine_datasets": [{ "binding": "<BINDING_NAME>", "dataset": "<DATASET_NAME>" }]`.
Call writeDataPoint synchronously and do NOT await it — it returns immediately and the runtime completes the write in the background: `env.WEATHER.writeDataPoint({ blobs: ["Seattle", "USA", "pro_sensor_9000"], doubles: [25, 0.5], indexes: ["a3cd45"] })`.
Put the dimensions you will GROUP BY or filter on in `blobs` (string array): city, country, customer id, route name, model name.
Put the numeric metrics you want to aggregate in `doubles` (number array): latency, temperature, token count, cost.
Use `indexes` for the sampling key — currently a single string, capped at 96 bytes. Choose a value with enough cardinality (e.g. a customer or user id) to keep samples representative under downsampling.
Query by POSTing raw SQL as the request body to `https://api.cloudflare.com/client/v4/accounts/<account_id>/analytics_engine/sql`.
Authenticate with `Authorization: Bearer <API_TOKEN>` using a token that has Account Analytics Read permission.
Smoke-test the pipe first: `curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" --header "Authorization: Bearer <API_TOKEN>" --data "SELECT 'Hello Workers Analytics Engine' AS message"`.
Query the dataset as a table named after the `dataset` value from the binding config — NOT the binding name: `SELECT blob1 AS probe_name, avg(double1) AS average_temp FROM temperature_readings GROUP BY probe_name`.
Reference fields positionally: `blob1`..`blob20`, `double1`..`double20`, `index1`, plus the built-in `timestamp` and `_sample_interval` columns.
Correct for sampling when aggregating: use `SUM(_sample_interval * double1)` rather than `SUM(double1)`, since each stored row can represent many original events once downsampling kicks in.
Use standard clauses as needed: WHERE (pre-aggregation), GROUP BY, HAVING (post-aggregation), ORDER BY, LIMIT, OFFSET, plus aggregate, string, date/time, math, bit, conditional, encoding, and type-conversion functions.
Select an output shape explicitly with the `FORMAT` SQL option; JSON (default), JSONEachRow, and TabSeparated are supported.
Official documentation (verify before relying on limits, which change): https://developers.cloudflare.com/analytics/analytics-engine/ | https://developers.cloudflare.com/analytics/analytics-engine/get-started/ | https://developers.cloudflare.com/analytics/analytics-engine/sql-api/ | https://developers.cloudflare.com/analytics/analytics-engine/sql-reference/ | https://developers.cloudflare.com/analytics/analytics-engine/limits/

Known gotchas

Each Worker invocation can write at most 250 data points.
Per data point: max 20 blobs, max 20 doubles, all blobs combined limited to 16 KB, and exactly one index capped at 96 bytes. Exceeding these truncates or rejects the write rather than throwing loudly.
Retention is only three months. Anything you need longer must be aggregated or exported elsewhere before it ages out — this is the constraint that most often forces a redesign.
Once write volume triggers downsampling, naive SUM or AVG over raw columns undercounts. You must multiply by `_sample_interval`, and a dashboard built before sampling kicked in will start reading low without any error.
The SQL table name is the `dataset` string from the binding config, not the `binding` property used in Worker code. Querying by the binding name returns a table-not-found error.
writeDataPoint must not be awaited. Treating it as a blocking call adds latency to the request path for no benefit.

Write high-cardinality custom events from a Worker with Analytics Engine writeDataPoint and query them via the SQL API

Documented steps

Known gotchas

Related routes

Give your agent this knowledge — and 15,800+ more routes

Need this verified for your stack — or a route we don't have yet?