Recommended Free Tools
Cloudflare has two distinct SQL routes: the Analytics SQL API for Cloudflare analytics and observability datasets, and the Workers Analytics Engine SQL API for custom data written by Workers. Pick the route that matches your data, authenticate with an API token, and check the SQL limits before connecting a BI client. Cloudflare documents a Grafana integration for Workers Analytics Engine; that does not mean every BI tool has a supported native connector.
Choose the Cloudflare SQL endpoint that matches your data
Cloudflare describes its general SQL API as a way to “query Cloudflare analytics and observability datasets with SQL.” It covers available Cloudflare product and account or zone analytics datasets. Workers Analytics Engine is different: it stores custom datapoints written by your Worker and is queried through an account-specific endpoint.
| Route | What you query | Endpoint | Important distinction |
|---|---|---|---|
| Analytics SQL API | Cloudflare analytics and observability datasets available to your account or zone | https://api.cloudflare.com/client/v4/analytics/sql |
Requires an authorized account or zone scope, a schema-qualified dataset, and a lower time bound. The supported SQL surface is constrained. |
| Workers Analytics Engine SQL API | Custom datasets populated by Workers | https://api.cloudflare.com/client/v4/accounts/<account_id>/analytics_engine/sql |
Uses a separate endpoint and dataset model. Rows include a sample interval, which can affect aggregations. |
These are not interchangeable database endpoints. Establish whether the records you need come from Cloudflare’s product analytics or from events your Worker explicitly writes, then use the corresponding API reference.
Run a query against the Analytics SQL API
Check access and dataset availability
Create an API token with the permissions required for the relevant analytics product and scope. Analytics read access alone may not grant access to every product dataset. Dataset and field availability can vary with plan and permissions. Consult Cloudflare’s SQL API overview and getting-started guide for current requirements.
#1 Best Overall
Send a JSON POST request
Cloudflare recommends JSON POST for this API. A request includes a SQL query and may include parameter values, scope, and time range. The query must select from one schema-qualified dataset. For example, the request shape is:
curl -X POST 'https://api.cloudflare.com/client/v4/analytics/sql'
-H 'Authorization: Bearer YOUR_API_TOKEN'
-H 'Content-Type: application/json'
--data '{
"query": "SELECT ... FROM schema.dataset WHERE ...",
"params": {},
"scope": {"...": "..."},
"time_range": {"start": "...", "end": "..."}
}'This is a request template, not a runnable query: replace the ellipses with a dataset, valid fields, and actual scope and time values from the relevant Cloudflare dataset. The request-level scope must specify exactly one account or zone tag. The time range requires a start and may include an end; bounds are inclusive. Cloudflare documents parameterized JSON requests in its query API reference.
- Use
paramsfor values supplied at runtime rather than concatenating user-provided values into SQL text. - Set tenancy in either request-level
scopeor SQL predicates, not both. - Set the time constraint in either request-level
time_rangeor a SQL time predicate, not both. - Use a lower time bound; do not assume an unbounded query is accepted.
Check the SQL before using a BI-generated query
The general Analytics SQL API is read-only and supports a documented subset, not arbitrary ClickHouse SQL. Common selection, filtering, grouping, ordering, and aggregation patterns are supported, but joins, unions, general subqueries, window functions, and data modification or definition statements are among the unsupported constructs. Review Cloudflare’s SQL language reference and test the exact query shape generated by your BI tool. A tool that emits unsupported SQL may need a simpler query or a different data-access approach.
Query data written to Workers Analytics Engine
Instrument and populate a dataset first
Workers Analytics Engine is for custom events and measurements written by a Worker, not a substitute endpoint for Cloudflare’s general analytics datasets. Define a dataset binding in the Worker configuration and write datapoints consistently; Cloudflare creates the dataset when data is first written. See the Workers Analytics Engine SQL API documentation for the endpoint and query details.
Account for sampling in calculations
Analytics Engine rows include a timestamp and _sample_interval. When sampling is in effect, a row can represent multiple events. Cloudflare’s examples adjust count and average calculations using that interval. Do not interpret a plain row count or average as an event-level statistic without applying the documented sampling treatment. The exact calculation depends on the metric and query; follow the examples and schema guidance in Cloudflare’s SQL API documentation.
Connect Grafana to Workers Analytics Engine
Cloudflare’s documented Grafana route uses the Altinity ClickHouse plugin to query Workers Analytics Engine. Configure the plugin with the account-specific endpoint and a custom bearer-token header. The documented integration is specific to this service and plugin; the available official guidance does not establish equivalent native setup recipes for every BI tool.
- Install or enable the Altinity ClickHouse data source plugin in Grafana.
- Set the connection URL to
https://api.cloudflare.com/client/v4/accounts/<account_id>/analytics_engine/sql, replacing<account_id>with your Cloudflare account ID. - Configure the custom HTTP header
Authorizationwith valueBearer YOUR_API_TOKEN. Keep the token secret and restrict its permissions appropriately. - Use the plugin to issue a query against the Analytics Engine dataset and verify the results against its schema, including sampling behavior.
Use Cloudflare’s Grafana integration guide for the current plugin settings and prerequisites.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Use the CLI for developer workflows, not as a BI connector
Cloudflare’s CLI offers cf sql query for running SQL queries and cf sql datasets for listing datasets. This can help developers inspect available data and validate a query before adapting it for a dashboard. It is a command-line workflow, not a BI connector.
Quick Recap
Best Value
Before relying on a dashboard
- Confirm whether the data belongs to the general Analytics SQL API or a Worker-written Analytics Engine dataset.
- Verify the token’s product permissions, account or zone scope, and the dataset and fields available to that identity.
- For the general API, ensure the query has one schema-qualified dataset and an applicable lower time bound, and keep request-level scope and time range from duplicating SQL predicates.
- Check generated SQL against the relevant service’s supported query surface; do not assume a BI tool’s generic ClickHouse mode guarantees compatibility.
- For Analytics Engine, validate whether sampling applies and use sampling-aware calculations.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
