# MTPLX GET /health Endpoint: Complete Runtime State Reference

> Explore the MTPLX GET /health endpoint for a full runtime state including model ID, sampling, API key needs, KV cache mode, and concurrency metrics. Monitor your MTPLX server effectively.

- Repository: [Youssof Altoukhi/MTPLX](https://github.com/youssofal/MTPLX)
- Tags: api-reference
- Published: 2026-09-05

---

**The `GET /health` endpoint returns a comprehensive JSON snapshot of the MTPLX API server's runtime state, including the loaded model identifier, active sampling parameters, API key requirements, KV cache quantization mode, and real-time concurrency metrics—containing no sensitive secrets and designed for monitoring dashboards.**

The `GET /health` endpoint in the `youssofal/MTPLX` repository serves as the primary diagnostic interface for the FastAPI server. Located in [`mtplx/server/openai.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/server/openai.py), this route aggregates telemetry from the model profile, backend configuration, and request scheduler into a single public-safe payload that health monitors, load balancers, and benchmarking tools consume to assess server readiness.

## Health Check Response Structure

When you query `GET /health`, MTPLX assembles a JSON object containing nine distinct top-level sections. Each field provides visibility into a specific subsystem without exposing secrets like raw API keys or model weights.

### Model Identity and Sampling Configuration

The **`model`** field returns the string identifier of the currently loaded model (e.g., `"mtplx-test-model"`). Nested within the **`profile`** object, you find `model_id` and `profile_default_model_id` distinguishing the active model from the default profile. The **`profile.sampler`** sub-object exposes the generation hyperparameters currently in effect, including `temperature`, `top_p`, and `top_k` values.

### Authentication and Security Flags

Two boolean and string fields govern access control:
- **`api_key_required`**: Boolean indicating if requests must include a bearer token.
- **`api_key_source`**: String describing the key origin (e.g., `"none"` when authentication is disabled).

According to the test suite in [`tests/test_server_openai.py`](https://github.com/youssofal/MTPLX/blob/main/tests/test_server_openai.py), these fields are validated to ensure the endpoint never leaks credential material while accurately reflecting security posture.

### Memory Management and Quantization

The **`paged_kv_quantization`** field reports the KV cache compression mode as `"off"`, `"q4"`, or `"q8"`, revealing how the server manages attention memory. Backend-specific implementations in [`mtplx/backends/qwen3_next.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/qwen3_next.py) (lines 39-45) and [`mtplx/backends/step3p5_mtp.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/step3p5_mtp.py) contribute these values based on the active model family’s capabilities.

### Runtime Concurrency and Thermal State

Real-time operational metrics include:
- **`active_requests`**: Integer count of in-flight generation jobs (normally `0` when idle).
- **`foreground_active`**: Integer count of foreground-priority tasks.
- **`last_request_started_at`**: Unix timestamp (seconds) of the most recent request start; returns `0.0` when the server has processed no requests since startup.
- **`thermal.max_requested`**: Boolean flag indicating whether "max-thermal" performance mode has been requested.

### Startup Metadata and Special Modes

The nested **`startup`** object contains process metadata populated during initialization:
- **`pid`**: The server process ID.
- **`warmup.ran`**: Boolean indicating whether the model warm-up phase completed.
- **`model_controls`**: Object detailing `model_family` (e.g., `"qwen3_8"`) and `draft_control.maximum` limits for speculative decoding.
- **`tool_prompt_mode`** and **`tool_contract_active`**: Strings and booleans describing the current tool-use configuration.

For deployments using the "opencode" short-context optimization, the payload includes **`opencode_short_context_depth2_tokens`** (nullable integer) and **`opencode_short_context_depth_policy`** (object with `type` and `depth` fields), as verified in [`tests/test_server_openai.py`](https://github.com/youssofal/MTPLX/blob/main/tests/test_server_openai.py) around lines 2516-2550.

## How to Call the GET /health Endpoint

### Basic curl Request

Query the endpoint from any HTTP client:

```bash
curl http://127.0.0.1:8000/health

```

**Sample JSON Response:**

```json
{
  "model": "mtplx-test-model",
  "profile": {
    "model_id": "mtplx-test-model",
    "profile_default_model_id": "mtplx-default",
    "sampler": { "temperature": 0.6, "top_p": 0.95, "top_k": 40 }
  },
  "api_key_required": false,
  "api_key_source": "none",
  "paged_kv_quantization": "q4",
  "warmup": { "ran": false },
  "startup": {
    "pid": 12345,
    "warmup": { "ran": false },
    "api_key_source": "none",
    "model_controls": {
      "model_family": "qwen3_8",
      "draft_control": { "maximum": 3 }
    },
    "tool_prompt_mode": "hybrid",
    "tool_contract_active": true
  },
  "thermal": { "max_requested": false },
  "foreground_active": 0,
  "active_requests": 0,
  "last_request_started_at": 0.0,
  "opencode_short_context_depth2_tokens": null,
  "opencode_short_context_depth_policy": { "type": "fixed", "depth": 2 }
}

```

### Python Client Integration

Use `requests` to programmatically check server status:

```python
import requests

resp = requests.get("http://127.0.0.1:8000/health")
health = resp.json()

print(f"Loaded model: {health['model']}")
print(f"Active generations: {health['active_requests']}")
print(f"Sampler temp: {health['profile']['sampler']['temperature']}")

# Check authentication requirements before sending sensitive prompts

if health["api_key_required"]:
    print("Warning: API key required for this endpoint")
else:
    print("No authentication required")

```

## Source Code Implementation

The health payload assembly occurs in [`mtplx/server/openai.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/server/openai.py) between lines 28630-28645, where the FastAPI route constructs the dictionary from runtime state objects. Backend modules such as [`mtplx/backends/qwen3_next.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/qwen3_next.py) inject family-specific values like draft control limits into the `startup.model_controls` section.

The response schema is regression-tested in [`tests/test_server_openai.py`](https://github.com/youssofal/MTPLX/blob/main/tests/test_server_openai.py) (lines 2505-2525), which asserts that `health.json()["model"]` matches the expected identifier and validates the sampler configuration structure at lines 2510-2515. These tests ensure that changes to the health payload remain backward compatible for monitoring integrations.

## Summary

- The **MTPLX `GET /health` endpoint** exposes a JSON object containing model identity, sampling parameters, authentication requirements, and runtime metrics.
- **Security-safe design** means the endpoint reveals whether keys are required (`api_key_required`) but never exposes the keys themselves.
- **Performance visibility** includes KV cache quantization mode (`paged_kv_quantization`), active request counts, and thermal throttling status.
- **Implementation** resides in [`mtplx/server/openai.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/server/openai.py) with backend contributions from files like [`mtplx/backends/qwen3_next.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/qwen3_next.py), verified by [`tests/test_server_openai.py`](https://github.com/youssofal/MTPLX/blob/main/tests/test_server_openai.py).

## Frequently Asked Questions

### Does the MTPLX GET /health endpoint expose sensitive API keys?

No. While the response includes `api_key_required` (boolean) and `api_key_source` (string indicating origin like `"none"`), it deliberately omits the actual secret material. This design allows public exposure for load balancer health checks without security risks.

### How can I determine if the model has finished warming up?

Check the `warmup.ran` field inside both the top-level and `startup` objects. A value of `true` indicates the initialization and warm-up sequence completed successfully. The test suite at [`tests/test_server_openai.py`](https://github.com/youssofal/MTPLX/blob/main/tests/test_server_openai.py) specifically validates this flag to ensure accurate readiness reporting.

### What does the `paged_kv_quantization` field indicate?

This field reports the compression level applied to the paged key-value cache, returning `"off"`, `"q4"`, or `"q8"`. This value originates from backend implementations such as [`mtplx/backends/qwen3_next.py`](https://github.com/youssofal/MTPLX/blob/main/mtplx/backends/qwen3_next.py) and helps operators verify memory optimization settings for the loaded model family.

### Why are `active_requests` and `foreground_active` sometimes zero when jobs are running?

These counters reflect instantaneous states sampled at request time. If you query `/health` between generation tokens or during scheduler idle cycles, transient counts may show zero. For precise concurrency tracking, poll the endpoint or correlate with `last_request_started_at` timestamps to detect recent activity.