Classification Report

Page Outline

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

---

GET/api/v1/models/{model_id}/performance/classification-report

The Classification Report endpoint generates a detailed, multi-class diagnostic matrix. Rather than just returning top-level aggregate scores, this API breaks down model performance label-by-label, surfacing the precise precision, recall, F1-scores, and support (instance count) for every single class category emitted by the model's output layer.

[!TIP] This endpoint is highly recommended for auditing model fairness or diagnosing bias. If overall accuracy is high but the macro-averaged F1 score is suspiciously low, checking the per-class report often reveals poor predictive capability on minority classes. To drill down into specific failures, use the Misclassification Errors endpoint.

Authentication Requirements

Access requires secure service-to-service or user authorization.

• Header: Authorization: Bearer <Your-JWT-Token>
• Permissions Required: The authenticated caller must have minimum model:read permissions for the specified organization tenant.

Path Parameters

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

Query Parameters

Parameter	Type	Default	Description
version_id	string	Latest Promoted	Scopes the report to a specific training iteration. Defaults to the promoted production tag.
dataset_split	string	test	Specifies the evaluation partition: train, validation, or test.
average	string	weighted	The mathematical averaging strategy applied to the overall score block. Accepts micro, macro, or weighted.

Operational Behavior

The backend logic adheres to strict formatting and computation rules:

1. Task Type Enforcement: This endpoint exclusively supports models with task_type: "classification" (binary or multi-class). Executing this against a regression architecture will immediately gracefully fail with an HTTP 422 Unprocessable Entity status.
2. Support Metric: The support field within the JSON response represents the exact ground-truth frequency of each target class found within the requested dataset_split.
3. Aggregation Logic: The overall response key provides a summarized view calculated using the requested average method, simplifying threshold checks for CI pipelines.

Response

The API responds with an HTTP 200 OK executing the payload as a structured ClassificationReport object.

Example JSON Response

{
  "model_id": "mdl-7f3a19bc92",
  "version_id": "ver-001a1",
  "dataset_split": "test",
  "per_class": {
    "not_churned": { 
      "precision": 0.9714, 
      "recall": 0.9602, 
      "f1_score": 0.9657, 
      "support": 9500 
    },
    "churned": { 
      "precision": 0.9189, 
      "recall": 0.9405, 
      "f1_score": 0.9295, 
      "support": 4500 
    }
  },
  "overall": {
    "accuracy": 0.9341,
    "precision": 0.9525,
    "recall": 0.9540,
    "f1_score": 0.9532,
    "average": "weighted"
  }
}

Error Codes

Ensure integrations handle these standardized rejection scenarios:

Code	Reason	Resolution
400	Bad Request	You provided an invalid aggregation strategy parameter (average).
401	Unauthorized	Verify your bearer token format and expiration.
404	Not Found	Check the model_id or version_id string for accuracy.
422	Unprocessable Entity	Target model is configured as a regression task; reports are classification-only.