Confusion Matrix

Page Outline

• Authentication Requirements
• Path Parameters
• Query Parameters
• Operational Behavior
• Response
  • Example JSON Response
• Error Codes

---

GET/api/v1/models/{model_id}/performance/confusion-matrix

The Confusion Matrix endpoint exports the exact mathematical distribution of a classification model's predictions mapped against ground-truth labels. This fundamental diagnostic tool vividly illustrates performance cross-talk—where an algorithm is consistently confusing one specific class for another—making it the essential API for debugging multi-class deep learning topologies.

[!TIP] While raw counts are helpful, the normalized output (normalize=true) is mathematically superior for comparing models trained on different split dataset sizes. Visualizing this data as a heatmap in your BI tool highlights False Positives and False Negatives instantly.

Authentication Requirements

This endpoint limits exposure of model predictions and requires authorization.

• Header: Authorization: Bearer <Your-JWT-Token>
• Permissions Required: The authenticated identity must possess model:read permissions inside the relevant organizational container.

Path Parameters

Parameter	Type	Required	Description
model_id	string	Yes	The unique identifier (mdl-xxx) of the classification system.

Query Parameters

Parameter	Type	Default	Description
version_id	string	Latest Promoted	Dictates the model iteration to inspect. Defaults to the active deployed version.
dataset_split	string	test	Target evaluation data partition. Valid inputs: train, validation, test.
normalize	boolean	false	Instructs the backend to return proportions bounded between [0.0, 1.0] (rows sum to 1) instead of absolute instance counts.

Operational Behavior

When computing the confusion matrix array, the analytics engine follows these paradigms:

1. Architecture Limitation: This metric only possesses mathematical meaning for task_type: "classification" architectures. If called against a regressional model, the operation halts with an HTTP 422 Unprocessable Entity.
2. Binary Structure: For two-class topologies, the matrix adheres to standard layout conventions: mapped rigorously to [True Positives, False Negatives], etc., following the labels ordering.
3. Multi-Class Expansion: For N-class prediction layers, the API guarantees the return of a perfectly square N✕N nested sub-matrix dynamically indexed to the returned labels array index.

Response

The system yields an HTTP 200 OK status equipped with a structured ConfusionMatrix schema. The array coordinates map logically as [Actual Labels][Predicted Labels].

Example JSON Response

{
  "model_id": "mdl-7f3a19bc92",
  "version_id": "ver-001a1",
  "dataset_split": "test",
  "labels": ["not_churned", "churned"],
  "matrix": [
    [9120, 380],
    [270, 4230]
  ],
  "normalized": false,
  "per_class_metrics": {
    "not_churned": { "precision": 0.971, "recall": 0.960, "f1_score": 0.965 },
    "churned": { "precision": 0.918, "recall": 0.940, "f1_score": 0.929 }
  }
}

Error Codes

Ensure your ingestion software handles the following edge-case states:

Code	Reason	Resolution
400	Bad Request	The normalize parameter was submitted with an invalid boolean type format.
401	Unauthorized	Required JWT token absent from header or cryptographically invalid.
404	Not Found	The model_id or targeted version_id string does not resolve to an asset.
422	Unprocessable Entity	The target model is configured for a regression objective type.