Headless BI & Metrics API | ATX AnalyticsTable Semantic Layer

Headless metrics — the semantic layer as an APIOne definition of revenue, served to every tool that asks — the same numbers the dashboards show. A metric that is defined twice is two metrics. If "Revenue" in the board pack and "revenue" in a Python notebook are written separately, they drift apart the first time a refund rule changes in one of them. Headless metrics serve the governed definitions in the semantic layer (Settings → Semantic objects) to any HTTP client. Notebooks, Power Automate, another BI tool, a data app and an LLM agent all get the same numbers the dashboards show.

Three endpoints

All three need the viewer role; the caller's grant on the metric's connection applies. Full schemas are in the API reference.

GET /api/v1/metrics lists the catalogue: measures, calculated members, dimensions, filters and parameters (?kind=, ?q=).
GET /api/v1/metrics/{id} returns one metric by URN or id. For a measure, it also returns compatibleDimensions: what it can be sliced by through declared joins.
POST /api/v1/metrics/query runs measures by dimensions, with filters, parameters, ordering and a limit.

Request

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. Results are 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 validated against the parameter's dataType and allowedValues and rendered 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 correct.
limit — 1–50 000, default 1 000. On SQL Server, Fabric and Synapse it becomes TOP n.
dryRun — true returns the plan only, without running anything.

Response

?format=csv or ?format=ndjson returns only the rows.

notes are part of the answer, not noise. The planner reports, for example, that a join is to-many and a SUM may double-count (fan-out), 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. It finds a spanning tree over the joins; a dataset with no path is refused with 422 planner_error, never cross-joined. Datasets on different connections are never joined.
Dialect-correct SQL. Identifier quoting (backticks on Databricks/MySQL), TOP on T-SQL, and date and boolean literals per connector kind.
Parameters are values, not SQL. They are validated and rendered as literals.
The caller's access applies. Running the query checks the caller's grant on the dataset's connection (object-level access). The licence must include the connector, and the call is audited as query.run with mode: metrics.

Errors

Every code, with its retry rule, is in the errors table.

A missing or invalid field, or an unknown or ambiguous reference — 400 bad_request, with field naming the culprit
Objects cannot be joined; a parameter value is invalid — 422 planner_error
The database rejects the SQL — 422 query_error
No grant on the connection — 403 forbidden

Recipes

Where the definitions come from

Semantic objects live in the user profile and are edited in Settings → Semantic objects — see the semantic model chapter of the handbook. A set is shipped between installations as a bundle (Export or Import JSON). The headless API reads the same store as the dashboards, so a definition changed there changes the API's answers at the same moment. That is the point.

Glossary terms on this page

ATX Institute on LinkedIn

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