# Platform Status API

Source: https://userguide.qualytics.io/settings/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](https://userguide.qualytics.io/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.

> **Note: 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](https://userguide.qualytics.io/settings/status/deep-dive/permissions/) page.

---

## Get Platform Info

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

**Endpoint**: `GET /api/`

Include the trailing slash. Requesting `/api` without it returns a redirect instead of the platform info.

**Permission**: Member user role

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> {
>   "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](https://userguide.qualytics.io/settings/status/deep-dive/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: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/status"
> ```
>
> **Response** (healthy Dataplane):
>
> ```json
> {
>   "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"`:
>
> ```json
> {
>   "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](https://userguide.qualytics.io/settings/status/deep-dive/dataplane-card/#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](https://userguide.qualytics.io/settings/status/deep-dive/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: Example request**
>
> **Request**:
>
> ```bash
> 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. |

> **Tip: 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](https://userguide.qualytics.io/settings/status/troubleshooting/).

---

## 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: Example request**
>
> **Request**:
>
> ```bash
> 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](https://userguide.qualytics.io/settings/status/how-tos/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. |

> **Example: Error response examples**
>
> **403 Forbidden**, unclassified, so `detail` only:
>
> ```json
> { "detail": "Not enough permissions" }
> ```
>
> **422 Unprocessable Entity**, classified and retryable:
>
> ```json
> {
>   "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](https://userguide.qualytics.io/settings/status/deep-dive/permissions/) page for details.

*Last updated: October 5, 2026.*