Platform Status API

The Status API lets you check the health of your Qualytics deployment, capture Dataplane diagnostics, and restart the Dataplane programmatically.

Tip

For complete API documentation, including request and response schemas, visit the API docs.

All endpoints are served from your Qualytics deployment, for example https://your-instance.qualytics.io. The paths below include the /api prefix. Authenticated endpoints take a bearer token.

Permissions

GET /api/status is public and needs no token. GET /api needs the Member role. GET /api/dataplane/diagnostics and PUT /api/admin/restart need the Admin role. See the Permissions page.

Get Platform Info

Retrieve the platform version, cloud provider, engine type, and deployment size.

Endpoint: GET /api

Permission: Member user role

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "application": "Qualytics",
  "description": "Data Quality Platform",
  "version": "20260404-5def6ae",
  "platform": "aws",
  "engine": "kubernetes",
  "size": "medium",
  "jwt_ttl_seconds": 3600
}

Platform Info Response Schema

Field	Type	Description
`application`	`string`	The application name.
`description`	`string`	The application description.
`version`	`string`	The platform version, in date-based format.
`platform`	`string`	The cloud provider: `aws`, `gcp`, `azure`, or `local`.
`engine`	`string`	The compute engine: `kubernetes`, `databricks`, or `local`.
`size`	`string`	The deployment size: `small`, `medium`, `large`, or `xlarge`.
`jwt_ttl_seconds`	`integer`	The session token time-to-live in seconds, for the provider that authenticated this request.

Info

For the UI equivalent, see the Deployment card.

Get Platform Status

Check the health of the database, RabbitMQ, and the Dataplane.

Endpoint: GET /api/status

Permission: Public, no token required

Note

This endpoint is public so the sign-in page can report a platform problem before anyone authenticates. It reports deployment health only, and exposes no datastore names, credentials, or data.

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/status"

Response (healthy Dataplane):

{
  "database_connection": "OK",
  "rabbitmq_connection": "OK",
  "dataplane_healthcheck": {
    "build_date": "2026-03-28",
    "implementation_version": "2.8.1",
    "git_hash": "60de4a5",
    "spark_version": "4.2.0",
    "driver_free_memory_mb": 4096,
    "max_executors": 8,
    "max_memory_per_executor_mb": 8192,
    "cores_per_executor": 4,
    "max_dataframe_size_mb": 2048,
    "thread_pool_parallelism": 16,
    "thread_pool_state": "2 running operations [48291, 48305] with 3 queued requests",
    "executor_capacity": {
      "status": "healthy",
      "live_executors": 6,
      "pending_tasks": 0,
      "capacity_slots": 24,
      "max_executors": 8
    },
    "sync_operation_parallelism": 4,
    "sync_admission": {
      "current_capacity": 4,
      "in_flight": 1,
      "waiting": 0,
      "floor": 2,
      "ceiling": 8,
      "process_cpu_percent": 31.4
    }
  }
}

Response (unhealthy Dataplane). When the engine does not answer, dataplane_healthcheck degrades to the string "UNHEALTHY":

{
  "database_connection": "OK",
  "rabbitmq_connection": "OK",
  "dataplane_healthcheck": "UNHEALTHY"
}

Platform Status Response Schema

Field	Type	Description
`database_connection`	`string`	Database connectivity: `OK` or `UNHEALTHY`.
`rabbitmq_connection`	`string`	Message broker connectivity: `OK` or `UNHEALTHY`.
`dataplane_healthcheck`	`string` or `object`	Either the string `UNHEALTHY`, or the Dataplane object described below.

Dataplane Fields

Field	Type	Description
`build_date`	`string`	The date the running Dataplane build was produced.
`implementation_version`	`string`	The version of the Dataplane.
`git_hash`	`string`	The build identifier of the Dataplane.
`spark_version`	`string`	The Apache Spark version.
`driver_free_memory_mb`	`integer`	Free memory on the engine driver, in MB.
`max_executors`	`integer`	Maximum number of executor nodes.
`max_memory_per_executor_mb`	`integer`	Maximum memory per executor, in MB.
`cores_per_executor`	`integer`	CPU cores per executor.
`max_dataframe_size_mb`	`integer`	Maximum dataframe size, in MB.
`thread_pool_parallelism`	`integer`	Maximum concurrent operations the engine will run.
`thread_pool_state`	`string`	Running operations with their IDs, and the number of queued requests.
`executor_capacity`	`object` or `null`	Live executor demand against capacity. Absent when the engine does not report it.
`sync_operation_parallelism`	`integer` or `null`	The concurrent Sync capacity currently granted. Absent when the engine does not report it.
`sync_admission`	`object` or `null`	Detail behind the Sync capacity grant. Absent when the engine does not report it.

Executor Capacity Object

Field	Type	Description
`status`	`string`	`healthy`, `unmet_demand_below_ceiling`, or `unmet_demand_at_ceiling`. The two unmet values drive the capacity warnings in the UI.
`live_executors`	`integer`	Executors currently running.
`pending_tasks`	`integer`	Tasks waiting for a slot.
`capacity_slots`	`integer`	Task slots the live executors provide.
`max_executors`	`integer`	The configured executor ceiling.

Sync Admission Object

Field	Type	Description
`current_capacity`	`integer`	Concurrent Sync operations currently allowed, adjusted automatically between the floor and the ceiling.
`in_flight`	`integer`	Sync operations running now.
`waiting`	`integer`	Sync operations waiting for a slot.
`floor`	`integer`	The lowest capacity the engine will drop to.
`ceiling`	`integer`	The configured maximum.
`process_cpu_percent`	`float` or `null`	Driver CPU load driving the adjustment. `null` until the engine's CPU sensor reports.

Note

git_hash, driver_free_memory_mb, and thread_pool_parallelism are returned by the API but not displayed in the UI.

Info

For the UI equivalent, see Platform Status.

Get Dataplane Diagnostics

Ask the Dataplane to render a diagnostics report and return it as a self-contained HTML page.

Endpoint: GET /api/dataplane/diagnostics

Permission: Admin user role

Note

The call triggers a live render on the engine and can take up to about 30 seconds. Nothing is stored, so each call returns the engine's state at that moment. There is no history endpoint.

Example request

Request:

curl -X GET "https://your-instance.qualytics.io/api/dataplane/diagnostics" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o dataplane-diagnostics.html

Response: 200 OK with Content-Type: text/html. The body is a standalone report that opens in any browser.

Status Code	Meaning
`200 OK`	The report was rendered and returned.
`408 Request Timeout`	The Dataplane did not answer within the timeout. A busy or undersized engine is the usual cause.
`422 Unprocessable Entity`	The Dataplane answered, but reported that it could not complete the request.
`502 Bad Gateway`	The Dataplane answered, but returned no usable report, or one that was corrupt or oversized.
`503 Service Unavailable`	The request could not be delivered to the Dataplane.

Deciding whether to retry

Only 200 returns a report. Do not decide whether to try again from the status code: a classified failure carries a fault_context object in the response body, and its retryable field is the authoritative signal.

Each failure is classified individually from what the engine reported, so the same status code can come back retryable on one call and not on the next. Engine failures such as capacity exhaustion, an unresponsive engine, or instability are classified as transient, which covers most diagnostics failures in practice, but read the flag rather than assuming it.

502 is the exception: the endpoint raises it directly, so it carries no fault_context. It means the engine answered but produced nothing usable, and a retry only helps once whatever blocked the render has cleared.

Info

For the UI equivalent and a full breakdown of the report's sections, see Dataplane Diagnostics.

Restart Dataplane

Send a graceful shutdown signal to the Dataplane. In a properly configured deployment, this triggers an immediate restart of the engine.

Endpoint: PUT /api/admin/restart

Permission: Admin user role

Note

This endpoint takes no request body. The restart is triggered by the request itself.

Example request

Request:

curl -X PUT "https://your-instance.qualytics.io/api/admin/restart" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 200 OK (empty body)

Warning

Restarting the Dataplane interrupts all in-flight operations. See Restart Dataplane for the full impact.

Info

The endpoint returns 200 OK once the shutdown signal is sent, without waiting for the restart to finish. There is no check for a restart already in progress, so repeated calls send repeated signals. Poll GET /api/status to see when the engine is back.

Error Responses

Status Code	Description
`401 Unauthorized`	Missing or invalid API token.
`403 Forbidden`	The user does not have the required role.
`408 Request Timeout`	The Dataplane did not answer within the timeout.
`422 Unprocessable Entity`	The Dataplane answered, but reported that it could not complete the request.
`502 Bad Gateway`	The Dataplane returned no usable diagnostics report.
`503 Service Unavailable`	The request could not be delivered to the Dataplane.

Errors classified by the platform carry a fault_context object alongside detail. Read its retryable field rather than inferring from the status code.

Field	Type	Description
`code`	`string`	The specific error, for example `DATAPLANE_AT_CAPACITY`.
`fault_domain`	`string`	Which system is responsible: `source_datastore`, `dataplane`, `controlplane`, `misconfiguration`, or `unknown`.
`who`	`string`	Who should act: `customer`, `qualytics`, `config`, or `unknown`.
`retryable`	`boolean`	Whether retrying the same request is likely to succeed.
`title`	`string`	Short user-facing summary of the failure.
`hint`	`string`	Suggested next step, ready to show to a user.
`phase`	`string` or `null`	Where a failed operation was in its lifecycle, such as `source_load` or `analysis`. `null` when it does not apply.

Error response examples

403 Forbidden, unclassified, so detail only:

{ "detail": "Not enough permissions" }

422 Unprocessable Entity, classified and retryable:

{
  "detail": "Your Qualytics dataplane is currently at capacity and could not process this request in time. Please try again shortly; if this persists, contact your administrator about scaling.",
  "fault_context": {
    "code": "DATAPLANE_AT_CAPACITY",
    "fault_domain": "dataplane",
    "who": "qualytics",
    "retryable": true,
    "title": "Our dataplane is too busy to complete the request",
    "hint": "Your Qualytics dataplane is at capacity. This may indicate temporary congestion or an undersized deployment. Retry shortly; if it persists, contact your administrator about scaling.",
    "phase": null
  }
}

Permission Summary

Operation	Minimum Permission
Get platform status	Public, no token required
Get platform info	Member user role
Get Dataplane diagnostics	Admin user role
Restart Dataplane	Admin user role

Note

The Status page in the UI requires the Manager role, which does not match the endpoints one-for-one. GET /api/status is public, and the diagnostics and restart endpoints are Admin-only. See the Permissions page for details.