Building Embedded Analytics on QuantumLayers
A first look at using QuantumLayers as a backend for charts, statistical analysis, and AI insights inside your own product. This post covers how the API fits together as a single endpoint pattern, how the three authentication paths work, and why embedding the analytics has become a smaller decision than building it.
The Part of the Roadmap Nobody Wants to Build
Almost every product eventually grows an analytics surface. Customers want to see their numbers, slice them, and understand what they mean. The feature sounds modest until you sketch what sits behind it. You need an ingestion path for messy customer data, a query layer that aggregates without buckling under load, a charting layer that turns rows into something legible, a statistics layer that handles correlation and distribution work correctly, and an AI layer that explains the result in plain language. By the time you have built all of that, you have built a second product inside your first one.
This post opens a short series on a different approach, which is to treat QuantumLayers as the analytics backend your application calls rather than something you rebuild in-house. Your app keeps owning the experience, meaning the interface, the authentication, and the product logic, while ingestion, querying, statistical computation, and insight generation happen behind a small and consistent API. I am not aiming for an exhaustive endpoint reference here, since the Embedded Analytics Developer Guide already covers that in detail. The focus is the high-level shape: how the API is organized and how you authenticate against it, so you can judge whether embedding beats building.
One Endpoint, Many Actions
The first thing worth knowing is that there is essentially one URL to talk to. Every call is an HTTP POST to a single endpoint, and an action field in the request body selects what you want to do. Fetching a chart, running an ANOVA, listing datasets, and scheduling a report are all the same request shape with a different action value and a few parameters. Every request carries a bearer token in the Authorization header, and every response comes back as JSON with a success flag and a data payload.
That uniformity is the whole ergonomic story. You write one small request helper that sets the URL, attaches the token, and posts a body, and from then on every capability in the platform becomes reachable by swapping the action string. There is no per-feature SDK to learn and no separate client for each analysis type. A correlation matrix and a scheduled PDF report are, mechanically, the same kind of call.
How Authentication Works
Authentication is where most embedding decisions are actually made, because it determines how your users and QuantumLayers users relate to each other. There are three paths, and which one you pick depends on where your code runs and whose data it touches.
The session token is the simplest case. When a user has signed in to QuantumLayers directly, their session token is available client-side, and you attach it to requests as a bearer token. This fits pages that live on the same origin and assume a logged-in QuantumLayers user. It is the easiest option when you are extending an experience for people who already have accounts.
The third-party JWT is the option that makes real embedding work, and it is worth understanding even at a high level. You register your application once with a provider ID and a shared secret. After that, your backend mints a short-lived signed token, a JWT that carries a stable user ID and email, then exchanges it for a QuantumLayers session. QuantumLayers finds or creates a shadow user keyed to your provider and that user ID, and keeps their details in sync on every login. The practical effect is that your users never see a QuantumLayers login screen. They sign in to your product, your server vouches for them, and the analytics account is provisioned quietly in the background. This is the path for SaaS products that want to embed analytics for their own customers.
The API token is the server-to-server option. You generate a long-lived token in your account and present it directly as a bearer token, with no browser, exchange step, or interactive sign-in involved. This suits backend scripts, scheduled jobs, and CI/CD pipelines that need to pull data or trigger analysis without a person in the loop. You set the lifetime when you create it, anywhere from short-lived to non-expiring for fixed infrastructure.
In short, the session token is for users already inside QuantumLayers, the JWT is for users inside your own app who should never need to know QuantumLayers exists, and the API token is for machines. Most embedded products end up using the JWT path for the front end and an API token for any backend automation.
The Endpoint Families
Although there is only one URL, the actions fall into a handful of families. You will not need all of them. Most integrations start with two or three and grow from there.
Dataset management is how data gets in. A dataset can come from a CSV upload or from a live connection to a SQL database, a REST API, an SFTP file, a Google Sheet, or a Kaggle dataset, and existing datasets can be joined into a merged one. Each source has its own create, update, and re-sync actions, but they all converge on the same idea. Once connected, a dataset is just an ID you pass to everything downstream. Listing your datasets is the natural first call in any integration, since it hands you the IDs the rest of the API revolves around.
Analytics and charting is where most embeds spend their time. You ask for a chart by dataset ID and chart type, such as bar, line, scatter, histogram, time series, box plot, or heatmap, and the response is a ready-to-render chart configuration rather than a pile of raw numbers you have to wire up yourself. There is also a recommended-charts action that inspects a dataset and returns a ranked set of the visualizations most worth showing, which is enough to populate a dashboard with no manual configuration at all.
Statistical analysis is the part you would least want to reimplement. A single action can return a full statistical summary per column, a correlation matrix, a distribution analysis with outlier detection, a principal component analysis, or a one-way ANOVA with effect sizes. The demanding work, including percentile math, skewness and kurtosis, significance testing, and dimensionality reduction, runs on the server and comes back as structured results. This is the same rigor we describe in Why Statistical Preprocessing Matters, exposed as endpoints you can call rather than code you have to own.
AI insights sit on top of the statistics. One action runs the full pipeline. Rule-based analyses surface what is statistically real, and an optional language-model pass turns the surviving findings into plain-language explanations and recommendations. The output is text your users can read, grounded in tests that already ran rather than a model guessing at a spreadsheet.
Beyond these, scheduled reports generate recurring PDF or HTML summaries by email, organization management handles multi-user accounts and shared datasets, and the QL-Agent action exposes a conversational layer that can orchestrate all of the above from a single natural-language prompt. If you want a chat-driven analytics surface instead of a fixed dashboard, you can embed the agent loop directly and pass the conversation history back on each turn.
What a First Integration Looks Like
Strip away the detail and the shape of a first integration is short. Your backend authenticates, either by minting a JWT for a signed-in user or by presenting an API token for an automated job, and receives a session it can use. It lists the available datasets to learn their IDs, then requests a chart, a statistical summary, or an insight for a chosen dataset and renders the result. That is a working embedded analytics feature, and none of those steps required you to build ingestion, write aggregation queries, or implement a single significance test.
The reason this stays simple as it grows is the uniformity we started with. Adding a correlation matrix next to your existing bar chart is the same call you already wrote with a different action. Moving from a static dashboard to a conversational one is, again, the same call shape pointed at the agent. The surface area you maintain barely changes as the capability expands.
Embedding Versus Building
The decision this series exists to inform is clear once the pieces are visible. Building analytics in-house means owning ingestion connectors, a query engine, a charting layer, a correct statistics implementation, and an AI explanation layer, and then maintaining all of it indefinitely. Embedding means writing one authenticated request helper and choosing which actions to call. The experience your users see is still entirely yours. What changes is how much of the machinery underneath you are responsible for keeping correct.
Later posts in this series will go a level deeper into each of these families, covering the authentication flow from end to end, the charting and statistical endpoints in practice, and embedding the QL-Agent as a conversational surface. For now, the architecture is the point worth remembering: one endpoint, three ways to authenticate, and a small set of action families that cover ingestion through insight. If that shape fits your product, the full mechanics are waiting in the Embedded Analytics Developer Guide.
This post opens the QuantumLayers blog series on building embedded analytics. For the complete endpoint and authentication reference, see the Embedded Analytics Developer Guide. For why the statistics underneath are worth keeping rather than rebuilding, see Why Statistical Preprocessing Matters. Start building on governed, statistically validated analytics at www.quantumlayers.com.