Get Performance Summary

Page Outline

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

---

GET/api/v1/models/{model_id}/performance/summary

The Get Performance Summary endpoint delivers the apex-level evaluation metrics for a fully trained model architecture. It is designed to furnish immediate, quantitative insights into how effectively the model generalizes on hold-out data. This endpoint is typically called by UI dashboards or CI/CD pipelines gating model deployment based on strict accuracy thresholds.

[!TIP] This endpoint provides a high-level overview. If you are conducting a deep-dive diagnostic on classification errors or exploring decision boundaries, query the specialized endpoints for the Confusion Matrix or Misclassification Errors.

Authentication Requirements

This endpoint requires secure authorization via a Bearer token.

• Header: Authorization: Bearer <Your-JWT-Token>
• Permissions Required: The authenticated user must have model:read or organization:viewer access rights for the targeted model.

Path Parameters

Parameter	Type	Required	Description
model_id	string	Yes	The unique identifier (mdl-xxx) of the model you are evaluating.

Query Parameters

Parameter	Type	Default	Description
version_id	string	Latest Promoted	The specific training iteration/version (ver-xxx). Defaults to the currently promoted production version if omitted.
dataset_split	string	test	The data partition used for evaluation scoring. Valid enumerations: train, validation, and test.

Operational Behavior

The backend metric calculation engine adheres to the following logic:

1. Task Type Resolution: The structure of the returned metrics payload maps directly to the model's underlying ML problem domain (e.g., classification returns AUC and F1-Score, while regression returns RMSE and R-Squared).
2. Split Enforcement: The endpoint strictly retrieves cached metric scores corresponding to the requested dataset_split. It does not execute dynamic, on-the-fly batch inference.
3. State Validation: If the requested model is currently in draft or training state and lacks completed historical versions to query against, the API returns an HTTP 422 Unprocessable Entity failure.

Response

Upon successful resolution, the API responds with an HTTP 200 OK status, returning a polymorphic PerformanceSummary JSON object containing the scored metrics.

Example JSON Response (Classification)

{
  "model_id": "mdl-7f3a19bc92",
  "version_id": "ver-001a1",
  "task_type": "classification",
  "dataset_split": "test",
  "metrics": {
    "accuracy": 0.9341,
    "precision": 0.9185,
    "recall": 0.9240,
    "f1_score": 0.9212,
    "roc_auc": 0.9678,
    "log_loss": 0.1425
  },
  "evaluated_at": "2026-03-13T14:22:10Z"
}

Error Codes

Implement reliable error handling strategies for these defined states:

Code	Reason	Resolution
400	Bad Request	You supplied an invalid enum for dataset_split.
401	Unauthorized	Verify your JWT token format and ensure it has not expired.
403	Forbidden	Ensure the user has minimum model:read permissions.
404	Not Found	The provided model_id or version_id cannot be located.
422	Unprocessable Entity	The model exists but currently holds no fully trained versions.