Headless BI:one governed metric layer for every app, agent and dashboard.
Headless BI separates the analytics engine from the interface. Your metric definitions, access rules and lineage live in one governed layer, and whatever reads from it, your product, your agents, a spreadsheet, gets the same answer.
What was net revenue retention by segment last quarter?
- Caller
- Your application
- You build
- The chart, the layout, the interactions
- Metric
- net_revenue_retention
- Status
- Certified
- Grain
- Segment by quarter
- Access
- Row-level security applied as the calling identity, at query time
- Lineage
- fct_subscription -> gl.revenue
- Audit
- Question, identity and rows returned, all logged
- Enforced in
- 0.3s, with no permission cache to flush
A worked example. The interfaces are real; the metric name, lineage path and grain stand in for yours.
- Runs on your warehouse, no data movement
- Certified metrics with lineage
- Row-level security at query time
- REST, MCP and SQL interfaces
What is headless BI?
Headless BI is business intelligence with the interface removed. The semantic layer, query engine and governance run as a service and deliver metrics by API to whatever needs them. Every consumer reads the same certified definitions.
The name borrows from headless CMS: managed centrally, delivered by API to whatever renders it.
Yours to choose, or to build
Whatever the answer is read in. A headless layer has no opinion about this, which is the entire point of it.
- Your product
- AI agents
- Spreadsheets
- Notebooks
- Your BI tool
- Internal services
Ours to run
The part that decides what a number means, who is allowed to see it, and how it is served. Shared by every head above.
- Semantic model
- Query engine
- Access control
- Lineage and audit
- REST, MCP, SQL
What headless BI is not
Not a ban on dashboards
Headless means the engine does not require a particular front end, not that charts are forbidden. A dashboard is simply one more head, and it can read the same definitions as everything else.
Not just a semantic layer
The semantic layer is the most important component of a headless deployment, not the whole of it. The query engine, the access control and the interfaces are what make the definitions reachable.
Not a database with a URL in front of it
Exposing tables over HTTP moves the problem rather than solving it. Without certified metrics and query-time access control, every consumer re-derives the business logic and the security.
Analytics does not have to arriveas somebody else's dashboard.
Each of these consumes the same certified metrics through the interface that suits it. That is what stops two of them reporting different numbers in the same meeting.
Your own product
Call the layer from your application and render results in your own components, your own design system, your own navigation. Nothing of ours appears.
Needs: a query interface and rows your UI can chart.
AI agents and copilots
An agent that can only reach raw tables has to infer your business logic, and it will sometimes infer it wrongly and confidently. One that reaches a certified metric inherits the definition instead.
Needs: tool definitions and a metric contract it can trust.
Spreadsheets
Finance will use a spreadsheet whatever else you build. Better that the number they are working from came out of the governed layer than out of a copy and paste three weeks ago.
Needs: a governed path that does not begin with an export.
Notebooks and data science
Start from the same certified definitions the rest of the business reports on, rather than rebuilding the metric in pandas and hoping it matches.
Needs: SQL access to governed results.
Services and workflows
Alerts, scheduled jobs, pricing rules and internal tools that need a number rather than a chart, and need it to be the same number the board saw.
Needs: a programmatic call and a stable contract.
The BI tool you already own
Headless does not mean replacing what works. Your existing dashboards become one more consumer of the same definitions.
Needs: a connection that respects the semantic layer.
Four components do the workthat a BI tool usually hides.
Pull the interface off a BI platform and this is what is left. Each piece is shared by every consumer, which is what makes the answers agree.
1. The semantic model
Metrics, dimensions, joins and grain, defined and certified once. This is the contract the whole business argues about before it is signed, and stops arguing about afterwards.
Certified metrics carry a status and a version, not just a formula.
2. The query engine
A plain-English question is resolved against the certified model and compiled to SQL that runs on your warehouse. Intent in, one unambiguous answer out, rather than a list of dashboards to dig through.
Queries execute in your warehouse, not on a copy of your data.
3. Access control
Permissions live in the query engine rather than in a dashboard filter, so they are resolved as the calling identity every time a query runs. Change a role and the next query respects it, because there is no permission cache to flush.
The same rules apply whether a person, an app or an agent asked.
4. The interfaces
REST for your application, MCP tools for agents and copilots, SQL passthrough for the consumers that already speak SQL. Different shapes of the same governed answer.
Adding a consumer is an integration, not a new access model.
Governance has to travel with the query,not with the dashboard.
The moment analytics leaves one interface, anything that was enforced inside that interface stops protecting you. So none of it is enforced there.
Row-level security at query time
Access is resolved as the calling identity when the query runs, and the database returns only authorized rows. A new consumer inherits the rules rather than reimplementing them.
Metrics certified once
A metric is defined, reviewed and certified in the semantic layer. Every consumer reads that definition, which is precisely why two of them cannot report different revenue.
Lineage on every answer
Each result traces back through the model to the source table it came from, whether a person asked or an agent did.
One audit trail
Questions, identities and results are logged centrally, so the record does not fragment across every tool that queries you.
Data stays where it is
Queries run against your warehouse in place. Nothing is copied to our infrastructure, so there is no extract to secure and no migration to sit through first.
No permission cache
Because entitlements are resolved per query rather than cached, a role change takes effect on the next question asked. There is no stale window to reason about.
Headless BI vs a semantic layer:related, and not the same thing.
The two terms get used interchangeably. The relationship is actually containment, and knowing which you are shopping for saves a procurement cycle.
The shared definition of what your data means.
Covers- Metrics and how they are calculated
- Dimensions, joins and grain
- The business names for technical fields
- Certification and versioning of definitions
That layer, plus everything needed to serve it.
Adds- A query engine that resolves questions against the model
- Access control enforced at query time, per identity
- Lineage and an audit trail on every answer
- REST, MCP and SQL interfaces for any consumer
- The operational job of keeping all of it running
The short version
A semantic layer tells you what a number means. Headless BI is what delivers that number, safely, to anything that asks. You can have a semantic layer without being headless, which is what every BI tool with a built-in modelling layer is. You cannot be meaningfully headless without one.
Embedded, white label, headless.The difference is who owns the interface.
All three run on the same engine, the same semantic layer and the same governance. They differ in how much of the surface is yours, and how much work that saves or creates.
Our whole product, carrying your brand.
Our engine, none of our interface.
| Attribute | Embedded | White label | Headless |
|---|---|---|---|
| What you get | Views you drop into your app | A branded analytics product | Governed query interfaces |
| Who builds the interface | We do | We do | You do |
| Whose brand shows | Yours, around our views | Yours, everywhere | Only yours, there is nothing else to see |
| Time to first value | Fastest | Fast | Depends on your build |
| Engineering required | Integration work | Configuration | Front-end build, then maintenance |
| Design control | Themeable | Themeable | Total |
| Who asks the questions | Your users, in your product | Your clients, in their own workspace | Whatever you point at the layer |
| Non-visual consumers | Not the purpose | Not the purpose | First-class: agents, jobs, services |
| Semantic layer | Shared | Shared | Shared |
| Governance and lineage | Enforced at query time | Enforced at query time | Enforced at query time |
| Typical buyer | Product teams | Agencies, consultancies, vertical SaaS | Platform and data engineering teams |
Most teams end up mixing them
Headless for the surface you care most about, embedded or white label for everything you would rather not build twice. The engine underneath does not change, so the numbers agree whichever route a given team took.
A metrics API is a weekend.The layer underneath it is the project.
Teams rarely underestimate the endpoint. They underestimate these, and these are the parts that keep needing attention long after launch.
The semantic layer
Metric definitions, dimensions, joins and grain, plus the review process that keeps them trustworthy as the business changes underneath them.
The access-control engine
Identity-aware row-level security that holds at query time, across every consumer, and does not quietly fail open the first time someone adds a new one.
The query engine
Turning a plain-English question into correct, performant SQL against your model, and being right often enough that people stop checking.
Lineage and audit
Tracing a number back to its source, and keeping a defensible record of who asked what, which your auditors will eventually ask to see.
The interfaces themselves
A REST surface, MCP tool definitions and a SQL path, each versioned and documented so your own consumers are not broken by your next change.
The upkeep after launch
New warehouse features, new models, new consumers, and the slow drift of definitions. This is the cost that outlives the build, and the one that never appears in the estimate.
Headless is the right answerfor some teams and the wrong one for others.
It trades our interface for total control, and that control is a build you own. Worth saying plainly before anyone books a call.
Choose headless if
- You have front-end engineers and a design system you intend to use.
- Analytics has to look and behave like the rest of your product, not like a widget inside it.
- Your most important consumers are not screens: agents, services, jobs and workflows.
- Several tools already report on the same metrics and they disagree.
- You want AI features answering from governed definitions rather than from raw tables.
- You are replacing a metrics layer you built and no longer want to maintain.
Choose embedded or white label if
- You need analytics in front of users in weeks, not after a front-end project.
- You have no front-end capacity to commit, now or for the maintenance afterwards.
- A themeable interface is close enough to what you would have designed anyway.
- You want to sell an analytics product without building one.
- You can only name one place the answers need to appear. One destination rarely repays a separate layer.