Headless metrics | ATX AnalyticsTable Docs

Headless metricsThe semantic layer as a service: list the metric catalogue, see what a measure can be sliced by, and query measures by dimensions with governed filters and typed parameters — the same numbers the dashboards show. The measures, dimensions, filters and parameters defined in Settings → Semantic objects can be queried over the API without building a dashboard. GET /api/v1/metrics lists them, and GET /api/v1/metrics/{id} shows one metric together with the dimensions it can be broken down by. POST /api/v1/metrics/query takes measures, dimensions, filters, parameter values, an order and a limit. The SAME planner the dashboards use then writes the SQL: it joins only through declared join objects, uses literals correct for the connection, validates parameters, and orders before the limit, so "top 10 regions" is right.

Headless metrics — the semantic layer as a service

The measures, dimensions, filters and parameters defined in Settings → Semantic objects can be queried over the API without building a dashboard. GET /api/v1/metrics lists them, and GET /api/v1/metrics/{id} shows one metric together with the dimensions it can be broken down by. POST /api/v1/metrics/query takes measures, dimensions, filters, parameter values, an order and a limit. The SAME planner the dashboards use then writes the SQL: it joins only through declared join objects, uses literals correct for the connection, validates parameters, and orders before the limit, so "top 10 regions" is right.
It runs the SQL on the dataset's connection under the caller's own grants. With dryRun the planned SQL is returned without running it. Read the notes in the answer: they report, for example, when a to-many join could make a sum count rows twice. A metric defined once and consumed everywhere is the point. A notebook and the board pack can no longer disagree about what revenue means.
GET — /api/v1/metrics — The catalogue: measures, calculated members, dimensions, filters and parameters (?kind=, ?q=)
GET — /api/v1/metrics/{id} — One object by URN or id; for a measure also compatibleDimensions — what it can be sliced by through declared joins
POST — /api/v1/metrics/query — Measures by dimensions, with filters, parameters, ordering and a limit

The request

{ "measures": ["revenue", "urn:analytics:calculated_member:avg_order_value"], "dimensions": ["region", "order_month"], "filters": ["completed_orders"], "parameters": { "start_date": "2026-01-01", "currency": "EUR" }, "orderBy": [{ "field": "revenue", "direction": "desc" }], "limit": 100, "dryRun": false }
measures — Required, 1–50. A measure or calculated-member URN, or a bare id. An id shared by two objects is refused as ambiguous; use the URN.
dimensions — 0–20 dimension references. The result is grouped by them.
filters — 0–50 semantic filter references, combined with AND. Free-form SQL filters are deliberately not accepted: a filter is a governed object too.
parameters — Keyed by parameter URN or id. Each value is checked against the parameter's type and allowed values and written as a literal in the connection's dialect.
orderBy — 0–10 entries; each field must also be requested. Ordering is applied before the limit, so "top 10 regions by revenue" is right.
limit — 1–50,000, default 1,000. On SQL Server, Fabric and Synapse it becomes TOP n.
dryRun — true returns the plan — the SQL and its columns — without running anything.

The response

{ "plan": { "sql": "SELECT region AS \"region\", SUM(amount) AS \"revenue\" FROM sales.orders WHERE (status = 'completed') GROUP BY region ORDER BY \"revenue\" DESC LIMIT 100", "connectionId": "conn-warehouse", "columns": [ { "alias": "region", "kind": "dimension", "urn": "urn:analytics:dimension:region" }, { "alias": "revenue", "kind": "measure", "urn": "urn:analytics:measure:revenue" } ], "notes": [] }, "data": { "columns": [ ... ], "rows": [ { "region": "EMEA", "revenue": 1234567.89 } ], "rowCount": 1, "nextCursor": null, "durationMs": 182 } }
?format=csv or ?format=ndjson returns only the rows.
notes are part of the answer. The planner reports, for example, that a join is to-many and a SUM may double-count, or that a comparison measure could not be joined and was dropped. Show them to whoever reads the numbers.

What the planner guarantees

Joins only through declared join objects. A dataset with no join path is refused with 422 planner_error — never cross-joined. Datasets on different connections are never joined.
SQL correct for the dialect: identifier quoting, TOP on T-SQL, date and boolean literals per connector.
Parameters are values, never SQL: checked, then written as literals.
The caller's access applies: the caller needs a grant on the dataset's connection, the licence must include the connector, and the call is audited as query.run with mode metrics.

Recipes

# What can I slice revenue by? curl -sS "$ATX_URL/api/v1/metrics/revenue" -H "Authorization: Bearer $ATX_TOKEN" | jq .compatibleDimensions # Monthly revenue as CSV for a spreadsheet refresh curl -sS -X POST "$ATX_URL/api/v1/metrics/query?format=csv" -H "Authorization: Bearer $ATX_TOKEN" \ -H "Content-Type: application/json" -d '{"measures":["revenue"],"dimensions":["order_month"],"orderBy":[{"field":"order_month"}]}' # What SQL would this run? Nothing is executed. curl ... -d '{"measures":["revenue"],"dimensions":["region"],"dryRun":true}' | jq -r .plan.sql
import pandas as pd, requests r = requests.post(f"{BASE}/metrics/query", headers=AUTH, json={"measures": ["revenue", "orders"], "dimensions": ["region"]}, timeout=120) r.raise_for_status() df = pd.DataFrame(r.json()["data"]["rows"])

Where the definitions come from

The API reads the same semantic objects as the dashboards — the ones edited under Settings → Semantic objects. A definition changed there changes the API's answers at the same moment, which is the point: a metric defined once cannot drift between the board pack and a notebook.
Edit the metric definitions: Settings → Settings → Set / Restore → Semantic objects

Glossary terms on this page

KPI dashboard: definition

ATX Institute on LinkedIn

This site needs JavaScript for the full experience. Every page above is reachable without it.