Service planes
Control, data, and combined service roles behind the InstantML API.
The InstantML API binary runs in one of three service-plane roles, and the hosted deployment splits control-plane and data-plane responsibilities behind one public API URL.
Service roles
| Role | Routes | Typical use |
|---|---|---|
combined | All control and data routes in one process. | Local development and single-binary self-hosting (the Docker Compose default). |
control | Auth, sessions, workspaces, seats, invitations, billing, API-key admin, dashboard preferences, and saved workspace views. | Hosted account service. |
data | Projects, runs, metrics, console logs, attributes, rich objects, artifacts, reports, imports, export, and usage. | Hosted tenant product service. |
Platform routes exist on every service regardless of role:
GET /healthGET /healthzGET /readyzGET /metricsGET /openapi.jsonGET /api/auth/config
/openapi.json and /api/auth/config report the active service plane, so you can verify which role served a request.
Hosted split topology
| Source | Route | Backing data |
|---|---|---|
| Browser / dashboard | Public HTTPS API URL | Control service for auth, billing, seats, API keys, preferences, and workspace views; data service for product reads. |
| Python SDK / uploader | Public HTTPS API URL | Data service for projects, runs, metrics, logs, artifacts, objects, reports, imports, export, and usage. |
| Control service | Control-plane Postgres | Account, session, billing, API-key, and tenant-route records. |
| Data service | Routed tenant ClickHouse databases | Tenant product records and metric tables. |
Requests are routed by path for a single data cell. A plain load balancer cannot inspect the workspace hidden inside a bearer token before authentication, so scaling to many cells adds a discovery step at the application layer rather than a central hot-path proxy.
The default hosted data store is InstantML-owned ClickHouse on Google Cloud. Premium workspaces can instead route their tenant data to customer-owned ClickHouse.
Readiness
/readyz fails until ClickHouse is reachable and the process-local control projection (tenant routes, memberships, API keys) has loaded. After that, a data-plane auth miss forces one control-record refresh and retry, so a freshly created API key or browser session becomes usable without waiting for the next background refresh.
Scaling posture
Control and data services scale conservatively to preserve tenant isolation, predictable routing, and consistent control-record replay. Teams that need stronger isolation, noisy-neighbor protection, or custom retention can run on a dedicated data cell or bring their own ClickHouse deployment.